From 3711f51a846e26eb87be86e4f7ffc18020285f79 Mon Sep 17 00:00:00 2001 From: Melech Lapson Date: Mon, 15 Apr 2024 12:04:09 -0500 Subject: [PATCH 01/10] switched links to using sphinx.ext.linkcode --- docs/conf.py | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++-- tox.ini | 3 ++ 2 files changed, 89 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index a0443d999c..29099d3616 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -31,8 +31,13 @@ Sphinx documentation builder """ -import os import datetime +import importlib +import inspect +import os +import re +from pathlib import Path + # Set env flag so that we can doc functions that may otherwise not be loaded # see for example interactive visualizations in qiskit.visualization. os.environ['QISKIT_DOCS'] = 'TRUE' @@ -64,7 +69,7 @@ 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.mathjax', - 'sphinx.ext.viewcode', + "sphinx.ext.linkcode", 'sphinx.ext.extlinks', 'jupyter_sphinx', 'reno.sphinxext', @@ -146,3 +151,82 @@ "matplotlib": ("https://matplotlib.org/stable/", None), "qiskit": ("https://docs.quantum.ibm.com/api/qiskit/", None), } + + +# ---------------------------------------------------------------------------------- +# 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_aer" 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}" + + github_branch = determine_github_branch() + return f"https://github.com/Qiskit/qiskit-aer/tree/{github_branch}/{file_name}{linespec}" diff --git a/tox.ini b/tox.ini index d537174f70..4214179ef4 100644 --- a/tox.ini +++ b/tox.ini @@ -10,6 +10,9 @@ setenv = LANGUAGE=en_US LC_ALL=en_US.utf-8 SETUPTOOLS_ENABLE_FEATURES=legacy-editable +passenv= + GITHUB_REF_NAME, + GITHUB_BASE_REF whitelist_externals = sh deps = -r requirements-dev.txt From 2fc46540f47a63a890cb72aae7fc87f90ef7e4d7 Mon Sep 17 00:00:00 2001 From: Melech Lapson Date: Mon, 15 Apr 2024 12:11:08 -0500 Subject: [PATCH 02/10] added release note --- ...ce_links_to_link_directly_to_github-bc554dee4f145c7b.yaml | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 releasenotes/notes/switch_source_links_to_link_directly_to_github-bc554dee4f145c7b.yaml diff --git a/releasenotes/notes/switch_source_links_to_link_directly_to_github-bc554dee4f145c7b.yaml b/releasenotes/notes/switch_source_links_to_link_directly_to_github-bc554dee4f145c7b.yaml new file mode 100644 index 0000000000..b369e78519 --- /dev/null +++ b/releasenotes/notes/switch_source_links_to_link_directly_to_github-bc554dee4f145c7b.yaml @@ -0,0 +1,5 @@ + +features: + - | + Source links in the API documentation will now link to the exact lines in the GitHub repository. + From 104c44f5699fccf9fee7f25a6d761624ea06aba4 Mon Sep 17 00:00:00 2001 From: Melech Lapson Date: Mon, 15 Apr 2024 13:38:00 -0500 Subject: [PATCH 03/10] added check for qiskit methods --- docs/conf.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 29099d3616..756f05615c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -229,4 +229,8 @@ def linkcode_resolve(domain, info): linespec = f"#L{lineno}-L{ending_lineno}" github_branch = determine_github_branch() - return f"https://github.com/Qiskit/qiskit-aer/tree/{github_branch}/{file_name}{linespec}" + if "qiskit/" in file_name: + base_url = "https://github.com/Qiskit/qiskit-aer/tree/" + else: + base_url = "https://github.com/Qiskit/qiskit/tree/" + return f"{base_url}{github_branch}/{file_name}{linespec}" From 9e3750edcbe1ff73758fb563e8c971d54632a789 Mon Sep 17 00:00:00 2001 From: Melech Lapson Date: Mon, 15 Apr 2024 13:38:32 -0500 Subject: [PATCH 04/10] remove whitespace --- docs/conf.py | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 756f05615c..67cfa4686c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -37,7 +37,6 @@ import os import re from pathlib import Path - # Set env flag so that we can doc functions that may otherwise not be loaded # see for example interactive visualizations in qiskit.visualization. os.environ['QISKIT_DOCS'] = 'TRUE' From 5599ec55e7c24c785f9d90642f7ff272beba68ca Mon Sep 17 00:00:00 2001 From: melechlapson Date: Mon, 15 Apr 2024 13:52:09 -0500 Subject: [PATCH 05/10] removed regex subsitution Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> --- docs/conf.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 67cfa4686c..198a4c2dc8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -214,8 +214,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 cef7fcf813bc48404caf954269a8203e4af284f7 Mon Sep 17 00:00:00 2001 From: melechlapson Date: Mon, 15 Apr 2024 13:54:04 -0500 Subject: [PATCH 06/10] Update tox.ini Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> --- tox.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tox.ini b/tox.ini index 4214179ef4..3ab790f5d1 100644 --- a/tox.ini +++ b/tox.ini @@ -11,7 +11,7 @@ setenv = LC_ALL=en_US.utf-8 SETUPTOOLS_ENABLE_FEATURES=legacy-editable passenv= - GITHUB_REF_NAME, + GITHUB_REF_NAME GITHUB_BASE_REF whitelist_externals = sh deps = From b996322f9fb7c886d7068c9f3ddc9c5913843e31 Mon Sep 17 00:00:00 2001 From: Melech Lapson Date: Mon, 15 Apr 2024 13:54:35 -0500 Subject: [PATCH 07/10] made updates following Eric's review --- docs/conf.py | 7 +++---- ..._links_to_link_directly_to_github-bc554dee4f145c7b.yaml | 5 ----- 2 files changed, 3 insertions(+), 9 deletions(-) delete mode 100644 releasenotes/notes/switch_source_links_to_link_directly_to_github-bc554dee4f145c7b.yaml diff --git a/docs/conf.py b/docs/conf.py index 67cfa4686c..afe7fbf357 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -227,9 +227,8 @@ def linkcode_resolve(domain, info): ending_lineno = lineno + len(source) - 1 linespec = f"#L{lineno}-L{ending_lineno}" - github_branch = determine_github_branch() if "qiskit/" in file_name: - base_url = "https://github.com/Qiskit/qiskit-aer/tree/" - else: base_url = "https://github.com/Qiskit/qiskit/tree/" - return f"{base_url}{github_branch}/{file_name}{linespec}" + else: + base_url = "https://github.com/Qiskit/qiskit-aer/tree/" + return f"{base_url}{GITHUB_BRANCH}/{file_name}{linespec}" diff --git a/releasenotes/notes/switch_source_links_to_link_directly_to_github-bc554dee4f145c7b.yaml b/releasenotes/notes/switch_source_links_to_link_directly_to_github-bc554dee4f145c7b.yaml deleted file mode 100644 index b369e78519..0000000000 --- a/releasenotes/notes/switch_source_links_to_link_directly_to_github-bc554dee4f145c7b.yaml +++ /dev/null @@ -1,5 +0,0 @@ - -features: - - | - Source links in the API documentation will now link to the exact lines in the GitHub repository. - From ec4099722d7a9c65eb47d1ca2f429509541c5504 Mon Sep 17 00:00:00 2001 From: Melech Lapson Date: Mon, 15 Apr 2024 13:58:15 -0500 Subject: [PATCH 08/10] made final line more readable --- docs/conf.py | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index f245f7f81d..426c59a23c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -226,8 +226,5 @@ def linkcode_resolve(domain, info): ending_lineno = lineno + len(source) - 1 linespec = f"#L{lineno}-L{ending_lineno}" - if "qiskit/" in file_name: - base_url = "https://github.com/Qiskit/qiskit/tree/" - else: - base_url = "https://github.com/Qiskit/qiskit-aer/tree/" - return f"{base_url}{GITHUB_BRANCH}/{file_name}{linespec}" + repo_name = "qiskit" if "qiskit/" in file_name else "qiskit-aer" + return f"https://github.com/Qiskit/{repo_name}/tree/{GITHUB_BRANCH}/{file_name}{linespec}" From 22788771889498be789e5b0d7944a71500ad6fdc Mon Sep 17 00:00:00 2001 From: Melech Lapson Date: Mon, 15 Apr 2024 15:43:47 -0500 Subject: [PATCH 09/10] cast filename to str --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 426c59a23c..2dc9016910 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -226,5 +226,5 @@ def linkcode_resolve(domain, info): ending_lineno = lineno + len(source) - 1 linespec = f"#L{lineno}-L{ending_lineno}" - repo_name = "qiskit" if "qiskit/" in file_name else "qiskit-aer" + repo_name = "qiskit" if "qiskit/" in str(file_name) else "qiskit-aer" return f"https://github.com/Qiskit/{repo_name}/tree/{GITHUB_BRANCH}/{file_name}{linespec}" From e37656cf2e4473374468b085ecdbe249d59b9804 Mon Sep 17 00:00:00 2001 From: Melech Lapson Date: Tue, 16 Apr 2024 12:04:04 -0500 Subject: [PATCH 10/10] re-added regex sub --- docs/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 2dc9016910..4dabf066ea 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -214,7 +214,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