Skip to content

Commit

Permalink
Use sphinx.ext.linkcode for more precise source code links (Qiskit#1431)
Browse files Browse the repository at this point in the history
* added .idea to .gitignore for Pycharm

* switched sphinx-ext-viewcode for sphinx-ext-linkcode

* remove leftover code from Azure

Co-authored-by: Eric Arellano <[email protected]>

* Update tox.ini

* remove leftover code from Azure part 2

Co-authored-by: Eric Arellano <[email protected]>

* change dashes to underscores

Co-authored-by: Eric Arellano <[email protected]>

* switch from qiskit to qiskit_ibm_runtime

Co-authored-by: Eric Arellano <[email protected]>

* remove leftover code from Azure part 3

Co-authored-by: Eric Arellano <[email protected]>

* final updates to determine_github_branch method

Co-authored-by: Eric Arellano <[email protected]>

* cha

Co-authored-by: Eric Arellano <[email protected]>

* added colon

* Fix issue with inherited methods

---------

Co-authored-by: Eric Arellano <[email protected]>
Co-authored-by: Kevin Tian <[email protected]>
  • Loading branch information
3 people committed Feb 28, 2024
1 parent f6f83a2 commit 16b247c
Show file tree
Hide file tree
Showing 3 changed files with 81 additions and 1 deletion.
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

0 comments on commit 16b247c

Please sign in to comment.