mirror of https://github.com/Qiskit/qiskit-aer.git
Use sphinx.ext.linkcode for more precise source code links (#2101)
* switched links to using sphinx.ext.linkcode * added release note * added check for qiskit methods * remove whitespace * removed regex subsitution Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> * Update tox.ini Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> * made updates following Eric's review * made final line more readable * cast filename to str * re-added regex sub --------- Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
This commit is contained in:
parent
cf510a2a45
commit
2a448ba0ae
87
docs/conf.py
87
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 @@ extensions = [
|
|||
'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 @@ intersphinx_mapping = {
|
|||
"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/<version>` 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}"
|
||||
|
|
Loading…
Reference in New Issue