From df0eb0ebfa04a7e33ba4bb7945fc7720cc9dcf0e Mon Sep 17 00:00:00 2001 From: John Zielke Date: Fri, 3 May 2024 16:39:05 +0000 Subject: [PATCH 1/3] Add direct links to github source code to docs Signed-off-by: John Zielke --- docs/_static/custom.css | 16 ++++++++++++++ docs/source/conf.py | 47 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 63 insertions(+) diff --git a/docs/_static/custom.css b/docs/_static/custom.css index e0a3457ca6..02a7f653d2 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -2,3 +2,19 @@ body{font-family:'Roboto',sans-serif;}.wy-menu-vertical p.caption{color:#7cccc7;} *{font-variant-ligatures: none;}.autoclasstoc td {padding:0.2rem;line-height:normal;} dl.field-list>dt{word-break: normal} + + +/* Instead of showing the [source] link for the github link, show a github icon */ +/* Give the empty span some content to make the background image show up */ +a.external > span.viewcode-link:after { + content: "\00a0\00a0\00a0"; +} +a.external > span.viewcode-link { + background: url(https://github.com/favicon.ico); + background-size: contain; + background-repeat: no-repeat; +} +/* Hide the [source] text */ +a.external > span.viewcode-link > span.pre { + display:none; +} diff --git a/docs/source/conf.py b/docs/source/conf.py index fdb10fbe03..af3c0a4092 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -13,6 +13,8 @@ import os import subprocess import sys +import importlib +import inspect sys.path.insert(0, os.path.abspath("..")) sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))) @@ -96,6 +98,7 @@ def generate_apidocs(*args): "sphinx.ext.napoleon", "sphinx.ext.autodoc", "sphinx.ext.viewcode", + "sphinx.ext.linkcode", "sphinx.ext.autosectionlabel", "sphinx.ext.autosummary", "sphinx_autodoc_typehints", @@ -162,3 +165,47 @@ def setup(app): # Hook to allow for automatic generation of API docs # before doc deployment begins. app.connect("builder-inited", generate_apidocs) + + +# -- Linkcode configuration -------------------------------------------------- +DEFAULT_REF = "main" +git_ref = os.environ.get("GITHUB_SHA", DEFAULT_REF) + +DEFAULT_REPOSITORY = "Project-MONAI/MONAI" +repository = os.environ.get("GITHUB_REPOSITORY", DEFAULT_REPOSITORY) + +base_code_url = f"https://github.com/{repository}/blob/{git_ref}" +MODULE_ROOT_FOLDER = "monai" + +# Adjusted from https://github.com/python-websockets/websockets/blob/main/docs/conf.py +def linkcode_resolve(domain, info): + if domain != "py": + raise ValueError(f"expected domain to be 'py', got {domain}." + "Please adjust linkcode_resolve to either handle this domain or ignore it.") + + mod = importlib.import_module(info["module"]) + if "." in info["fullname"]: + objname, attrname = info["fullname"].split(".") + obj = getattr(mod, objname) + try: + # object is a method of a class + obj = getattr(obj, attrname) + except AttributeError: + # object is an attribute of a class + return None + else: + obj = getattr(mod, info["fullname"]) + + try: + file = inspect.getsourcefile(obj) + lines = inspect.getsourcelines(obj) + except TypeError: + # e.g. object is a typing.Union + return None + file = os.path.relpath(file, os.path.abspath("..")) + if not file.startswith(MODULE_ROOT_FOLDER): + # e.g. object is a typing.NewType + return None + start, end = lines[1], lines[1] + len(lines[0]) - 1 + url = f"{base_code_url}/{file}#L{start}-L{end}" + return url From 4fe864cb81def14e221883113ab1fe09ad7711d2 Mon Sep 17 00:00:00 2001 From: John Zielke Date: Fri, 3 May 2024 17:01:34 +0000 Subject: [PATCH 2/3] Fix formatting Signed-off-by: John Zielke --- docs/source/conf.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index af3c0a4092..fc52d61db0 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -177,11 +177,14 @@ def setup(app): base_code_url = f"https://github.com/{repository}/blob/{git_ref}" MODULE_ROOT_FOLDER = "monai" + # Adjusted from https://github.com/python-websockets/websockets/blob/main/docs/conf.py def linkcode_resolve(domain, info): if domain != "py": - raise ValueError(f"expected domain to be 'py', got {domain}." - "Please adjust linkcode_resolve to either handle this domain or ignore it.") + raise ValueError( + f"expected domain to be 'py', got {domain}." + "Please adjust linkcode_resolve to either handle this domain or ignore it." + ) mod = importlib.import_module(info["module"]) if "." in info["fullname"]: From cb8d8c7cf099b73633f23703115c9c9edb0e0be1 Mon Sep 17 00:00:00 2001 From: John Zielke Date: Mon, 13 May 2024 20:18:52 +0000 Subject: [PATCH 3/3] Fix default ref; Use [source] as link; Remove viewcode extension Signed-off-by: John Zielke --- docs/_static/custom.css | 16 ---------------- docs/source/conf.py | 13 ++++++++----- 2 files changed, 8 insertions(+), 21 deletions(-) diff --git a/docs/_static/custom.css b/docs/_static/custom.css index 02a7f653d2..e0a3457ca6 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -2,19 +2,3 @@ body{font-family:'Roboto',sans-serif;}.wy-menu-vertical p.caption{color:#7cccc7;} *{font-variant-ligatures: none;}.autoclasstoc td {padding:0.2rem;line-height:normal;} dl.field-list>dt{word-break: normal} - - -/* Instead of showing the [source] link for the github link, show a github icon */ -/* Give the empty span some content to make the background image show up */ -a.external > span.viewcode-link:after { - content: "\00a0\00a0\00a0"; -} -a.external > span.viewcode-link { - background: url(https://github.com/favicon.ico); - background-size: contain; - background-repeat: no-repeat; -} -/* Hide the [source] text */ -a.external > span.viewcode-link > span.pre { - display:none; -} diff --git a/docs/source/conf.py b/docs/source/conf.py index fc52d61db0..782b585c9f 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -97,7 +97,6 @@ def generate_apidocs(*args): "sphinx.ext.mathjax", "sphinx.ext.napoleon", "sphinx.ext.autodoc", - "sphinx.ext.viewcode", "sphinx.ext.linkcode", "sphinx.ext.autosectionlabel", "sphinx.ext.autosummary", @@ -168,8 +167,12 @@ def setup(app): # -- Linkcode configuration -------------------------------------------------- -DEFAULT_REF = "main" -git_ref = os.environ.get("GITHUB_SHA", DEFAULT_REF) +DEFAULT_REF = "dev" +if os.environ.get("GITHUB_REF_TYPE", "branch") == "tag": + # When building a tag, link to the tag itself + git_ref = os.environ.get("GITHUB_REF", DEFAULT_REF) +else: + git_ref = os.environ.get("GITHUB_SHA", DEFAULT_REF) DEFAULT_REPOSITORY = "Project-MONAI/MONAI" repository = os.environ.get("GITHUB_REPOSITORY", DEFAULT_REPOSITORY) @@ -201,7 +204,7 @@ def linkcode_resolve(domain, info): try: file = inspect.getsourcefile(obj) - lines = inspect.getsourcelines(obj) + source, lineno = inspect.getsourcelines(obj) except TypeError: # e.g. object is a typing.Union return None @@ -209,6 +212,6 @@ def linkcode_resolve(domain, info): if not file.startswith(MODULE_ROOT_FOLDER): # e.g. object is a typing.NewType return None - start, end = lines[1], lines[1] + len(lines[0]) - 1 + start, end = lineno, lineno + len(source) - 1 url = f"{base_code_url}/{file}#L{start}-L{end}" return url