Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use sphinx.ext.linkcode for more precise source code links (Cherry-pick of #1431) #1438

Merged
merged 1 commit into from
Feb 28, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -107,3 +107,6 @@ Qconfig.py
.DS_Store

/docs/stubs/

# Pycharm
.idea
76 changes: 75 additions & 1 deletion docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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('.'))
Expand All @@ -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',
Expand Down Expand Up @@ -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/<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
)


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}"
3 changes: 3 additions & 0 deletions tox.ini
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading