From 455c5762e3f688bc2026c058ed838c45bd8e52c4 Mon Sep 17 00:00:00 2001 From: Melech Lapson Date: Mon, 15 Apr 2024 14:03:14 -0500 Subject: [PATCH 1/7] switched to using linkcode exception --- docs/conf.py | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 82 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index d25043d5..0264d3a1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,8 +18,12 @@ import datetime import doctest +import importlib +import inspect import os +import re import sys +from pathlib import Path import qiskit_algorithms @@ -46,7 +50,7 @@ "sphinx.ext.autodoc", "sphinx.ext.autosummary", "sphinx.ext.mathjax", - "sphinx.ext.viewcode", + "sphinx.ext.linkcode", "sphinx.ext.extlinks", "sphinx.ext.intersphinx", "sphinx.ext.doctest", @@ -164,3 +168,80 @@ # >> code # output doctest_test_doctest_blocks = "" +# ---------------------------------------------------------------------------------- +# Source code links +# ---------------------------------------------------------------------------------- + +def determine_github_branch() -> str: + """Determine the GitHub branch name to use for source code links. + + We need to decide whether to use `stable/` vs. `main` for dev builds. + Refer to https://docs.github.com/en/actions/learn-github-actions/variables + for how we determine this with GitHub Actions. + """ + # If CI env vars not set, default to `main`. This is relevant for local builds. + if "GITHUB_REF_NAME" not in os.environ: + return "main" + + # PR workflows set the branch they're merging into. + if base_ref := os.environ.get("GITHUB_BASE_REF"): + return base_ref + + ref_name = os.environ["GITHUB_REF_NAME"] + + # Check if the ref_name is a tag like `1.0.0` or `1.0.0rc1`. If so, we need + # to transform it to a Git branch like `stable/1.0`. + version_without_patch = re.match(r"(\d+\.\d+)", ref_name) + return ( + f"stable/{version_without_patch.group()}" + if version_without_patch + else ref_name + ) + + +REPO_ROOT = Path(__file__).resolve().parents[1] +GITHUB_BRANCH = determine_github_branch() + + +def linkcode_resolve(domain, info): + if domain != "py": + return None + + module_name = info["module"] + if "qiskit_algorithms" not in module_name: + return None + + try: + module = importlib.import_module(module_name) + except ModuleNotFoundError: + return None + + obj = module + for part in info["fullname"].split("."): + try: + obj = getattr(obj, part) + except AttributeError: + return None + + try: + full_file_name = inspect.getsourcefile(obj) + except TypeError: + return None + if full_file_name is None: + return None + try: + relative_file_name = Path(full_file_name).resolve().relative_to(REPO_ROOT) + file_name = re.sub(r"\.tox\/.+\/site-packages\/", "", str(relative_file_name)) + except ValueError: + return None + + try: + source, lineno = inspect.getsourcelines(obj) + except (OSError, TypeError): + linespec = "" + else: + ending_lineno = lineno + len(source) - 1 + linespec = f"#L{lineno}-L{ending_lineno}" + + repo_name = "Qiskit/qiskit/" if "qiskit/" in file_name else "qiskit-community/qiskit-algorithms" + return f"https://github.com/{repo_name}/tree/{GITHUB_BRANCH}/{file_name}{linespec}" From afd7d2f85bf1fb031ee47dc36b71db53da84e6c2 Mon Sep 17 00:00:00 2001 From: Melech Lapson Date: Mon, 15 Apr 2024 14:08:43 -0500 Subject: [PATCH 2/7] removed regex subsitution --- docs/conf.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 0264d3a1..acb033a7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -230,8 +230,7 @@ def linkcode_resolve(domain, info): if full_file_name is None: return None try: - relative_file_name = Path(full_file_name).resolve().relative_to(REPO_ROOT) - file_name = re.sub(r"\.tox\/.+\/site-packages\/", "", str(relative_file_name)) + file_name = Path(full_file_name).resolve().relative_to(REPO_ROOT) except ValueError: return None From c6b0113619e25ff1a3241209314d77a1d390c7ac Mon Sep 17 00:00:00 2001 From: Melech Lapson Date: Mon, 15 Apr 2024 15:44:47 -0500 Subject: [PATCH 3/7] Update conf.py --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index acb033a7..552efd5c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -242,5 +242,5 @@ def linkcode_resolve(domain, info): ending_lineno = lineno + len(source) - 1 linespec = f"#L{lineno}-L{ending_lineno}" - repo_name = "Qiskit/qiskit/" if "qiskit/" in file_name else "qiskit-community/qiskit-algorithms" + repo_name = "Qiskit/qiskit/" if "qiskit/" in str(file_name) else "qiskit-community/qiskit-algorithms" return f"https://github.com/{repo_name}/tree/{GITHUB_BRANCH}/{file_name}{linespec}" From bc69088e9e82a1ec233e5553876e74690700f419 Mon Sep 17 00:00:00 2001 From: Melech Lapson Date: Mon, 15 Apr 2024 17:09:26 -0500 Subject: [PATCH 4/7] added regex sub for qiskit refs --- docs/conf.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 552efd5c..82a97edd 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -230,7 +230,8 @@ def linkcode_resolve(domain, info): if full_file_name is None: return None try: - file_name = Path(full_file_name).resolve().relative_to(REPO_ROOT) + relative_file_name = Path(full_file_name).resolve().relative_to(REPO_ROOT) + file_name = re.sub(r"\.tox\/.+\/site-packages\/", "", str(relative_file_name)) except ValueError: return None @@ -242,5 +243,6 @@ def linkcode_resolve(domain, info): ending_lineno = lineno + len(source) - 1 linespec = f"#L{lineno}-L{ending_lineno}" - repo_name = "Qiskit/qiskit/" if "qiskit/" in str(file_name) else "qiskit-community/qiskit-algorithms" + repo_name = "Qiskit/qiskit/" if "qiskit/" in str(file_name) else \ + "qiskit-community/qiskit-algorithms" return f"https://github.com/{repo_name}/tree/{GITHUB_BRANCH}/{file_name}{linespec}" From e80bbbc2a156c41c91fc7081351da4f052384f1e Mon Sep 17 00:00:00 2001 From: Melech Lapson Date: Tue, 16 Apr 2024 15:50:09 -0500 Subject: [PATCH 5/7] reformat file --- docs/conf.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 82a97edd..8cb48a51 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -231,7 +231,9 @@ def linkcode_resolve(domain, info): return None try: relative_file_name = Path(full_file_name).resolve().relative_to(REPO_ROOT) - file_name = re.sub(r"\.tox\/.+\/site-packages\/", "", str(relative_file_name)) + file_name = re.sub(r"\.tox\/.+\/site-packages\/", + "", + str(relative_file_name)) except ValueError: return None From 72a5c603c1487f2f2cfeef02b63a26738f58e950 Mon Sep 17 00:00:00 2001 From: Melech Lapson Date: Fri, 19 Apr 2024 10:19:29 -0500 Subject: [PATCH 6/7] reset formatting --- docs/conf.py | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 8cb48a51..335aff31 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -230,10 +230,8 @@ def linkcode_resolve(domain, info): if full_file_name is None: return None try: - relative_file_name = Path(full_file_name).resolve().relative_to(REPO_ROOT) - file_name = re.sub(r"\.tox\/.+\/site-packages\/", - "", - str(relative_file_name)) + relative_file_name = (Path(full_file_name).resolve().relative_to(REPO_ROOT)) + file_name = re.sub(r"\.tox\/.+\/site-packages\/", "", str(relative_file_name)) except ValueError: return None From b4cc8f3489d1f8e55beceec1e77f4718e96cc6bb Mon Sep 17 00:00:00 2001 From: Melech Lapson Date: Fri, 19 Apr 2024 11:50:59 -0500 Subject: [PATCH 7/7] fixed formatting --- docs/conf.py | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 335aff31..8bbed2d4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -172,6 +172,7 @@ # Source code links # ---------------------------------------------------------------------------------- + def determine_github_branch() -> str: """Determine the GitHub branch name to use for source code links. @@ -192,11 +193,7 @@ def determine_github_branch() -> str: # Check if the ref_name is a tag like `1.0.0` or `1.0.0rc1`. If so, we need # to transform it to a Git branch like `stable/1.0`. version_without_patch = re.match(r"(\d+\.\d+)", ref_name) - return ( - f"stable/{version_without_patch.group()}" - if version_without_patch - else ref_name - ) + return f"stable/{version_without_patch.group()}" if version_without_patch else ref_name REPO_ROOT = Path(__file__).resolve().parents[1] @@ -230,7 +227,7 @@ def linkcode_resolve(domain, info): if full_file_name is None: return None try: - relative_file_name = (Path(full_file_name).resolve().relative_to(REPO_ROOT)) + relative_file_name = Path(full_file_name).resolve().relative_to(REPO_ROOT) file_name = re.sub(r"\.tox\/.+\/site-packages\/", "", str(relative_file_name)) except ValueError: return None @@ -243,6 +240,7 @@ def linkcode_resolve(domain, info): ending_lineno = lineno + len(source) - 1 linespec = f"#L{lineno}-L{ending_lineno}" - repo_name = "Qiskit/qiskit/" if "qiskit/" in str(file_name) else \ - "qiskit-community/qiskit-algorithms" + repo_name = ( + "Qiskit/qiskit/" if "qiskit/" in str(file_name) else "qiskit-community/qiskit-algorithms" + ) return f"https://github.com/{repo_name}/tree/{GITHUB_BRANCH}/{file_name}{linespec}"