diff --git a/docs/conf.py b/docs/conf.py index a0443d999c..4dabf066ea 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -31,8 +31,12 @@ 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 +68,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 +150,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}" + + 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}" diff --git a/tox.ini b/tox.ini index d537174f70..3ab790f5d1 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