From 16b247c29c9d7f33095975a3e31191d1662fbeec Mon Sep 17 00:00:00 2001 From: melechlapson Date: Wed, 28 Feb 2024 08:24:00 -0600 Subject: [PATCH] Use sphinx.ext.linkcode for more precise source code links (#1431) * added .idea to .gitignore for Pycharm * switched sphinx-ext-viewcode for sphinx-ext-linkcode * remove leftover code from Azure Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> * Update tox.ini * remove leftover code from Azure part 2 Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> * change dashes to underscores Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> * switch from qiskit to qiskit_ibm_runtime Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> * remove leftover code from Azure part 3 Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> * final updates to determine_github_branch method Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> * cha Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> * added colon * Fix issue with inherited methods --------- Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> Co-authored-by: Kevin Tian --- .gitignore | 3 +++ docs/conf.py | 76 +++++++++++++++++++++++++++++++++++++++++++++++++++- tox.ini | 3 +++ 3 files changed, 81 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index a4393ae2a..7c875878e 100644 --- a/.gitignore +++ b/.gitignore @@ -107,3 +107,6 @@ Qconfig.py .DS_Store /docs/stubs/ + +# Pycharm +.idea \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 1f40f4419..24e3aae9c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -11,7 +11,9 @@ # that they have been altered from the originals. # -- Path setup -------------------------------------------------------------- +import inspect import os +import re import sys sys.path.insert(0, os.path.abspath('.')) @@ -34,7 +36,7 @@ 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', # This is used by qiskit/documentation to generate links to github.com. - "sphinx.ext.viewcode", + "sphinx.ext.linkcode", 'jupyter_sphinx', 'sphinx_autodoc_typehints', 'reno.sphinxext', @@ -117,3 +119,75 @@ html_last_updated_fmt = '%Y/%m/%d' html_sourcelink_suffix = '' autoclass_content = 'both' + + +# ---------------------------------------------------------------------------------- +# 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 + ) + + +GITHUB_BRANCH = determine_github_branch() + + +def linkcode_resolve(domain, info): + if domain != "py": + return None + + module_name = info["module"] + module = sys.modules.get(module_name) + if module is None or "qiskit_ibm_runtime" not in module_name: + return None + + obj = module + for part in info["fullname"].split("."): + try: + obj = getattr(obj, part) + except AttributeError: + return None + is_valid_code_object = ( + inspect.isclass(obj) or inspect.ismethod(obj) or inspect.isfunction(obj) + ) + if not is_valid_code_object: + return None + try: + full_file_name = inspect.getsourcefile(obj) + except TypeError: + return None + if full_file_name is None or "/qiskit_ibm_runtime/" not in full_file_name: + return None + file_name = full_file_name.split("/qiskit_ibm_runtime/")[-1] + + try: + source, lineno = inspect.getsourcelines(obj) + except (OSError, TypeError): + linespec = "" + else: + ending_lineno = lineno + len(source) - 1 + linespec = f"#L{lineno}-L{ending_lineno}" + return f"https://github.com/Qiskit/qiskit-ibm-runtime/tree/{GITHUB_BRANCH}/qiskit_ibm_runtime/{file_name}{linespec}" diff --git a/tox.ini b/tox.ini index f219e404e..c42394b21 100644 --- a/tox.ini +++ b/tox.ini @@ -10,6 +10,9 @@ setenv = VIRTUAL_ENV={envdir} LANGUAGE=en_US LC_ALL=en_US.utf-8 +passenv= + GITHUB_REF_NAME, + GITHUB_BASE_REF deps = -r{toxinidir}/requirements.txt -r{toxinidir}/requirements-dev.txt