Use sphinx.ext.linkcode for more precise source code links

.github/workflows/docs_deploy.yml

@@ -19,19 +19,30 @@ jobs:
         with:
           # We need to fetch the whole history so 'reno' can do its job and we can inspect tags.
           fetch-depth: 0
-
       - uses: actions/setup-python@v5
         name: Install Python
         with:
           # Sync with 'documentationPythonVersion' in 'azure-pipelines.yml'.
           python-version: '3.9'
-
       - name: Install dependencies
         run: tools/install_ubuntu_docs_dependencies.sh
 
+      - name: Determine GitHub branch name
+        run: |
+          # PR workflows set the branch they're merging into.
+          if [ -n "$GITHUB_BASE_REF" ]; then
+            BRANCH_NAME="$GITHUB_BASE_REF"
+          # Tags like 1.0.0 and 1.0.0rc1 should point to their stable branch.
+          elif [[ $GITHUB_REF_NAME =~ ^([0-9]+\.[0-9]+) ]]; then
+            BRANCH_NAME="stable/${BASH_REMATCH[1]}"
+          else
+              BRANCH_NAME="$GITHUB_REF_NAME"
+          fi
+          echo "Using branch '${BRANCH_NAME}' for GitHub source code links"
+          echo "QISKIT_DOCS_GITHUB_BRANCH_NAME=$BRANCH_NAME" >> $GITHUB_ENV
+
       - name: Build documentation
         run: tox run -e docs
-
       - name: Store built documentation artifact
         uses: actions/upload-artifact@v4
         with:

docs/conf.py

@@ -11,13 +11,17 @@
 # that they have been altered from the originals.
 
 from __future__ import annotations
-
 # pylint: disable=invalid-name,missing-function-docstring
 
 """Sphinx documentation builder."""
 
 import datetime
 import doctest
+import importlib
+import inspect
+import os
+import re
+
 
 project = "Qiskit"
 project_copyright = f"2017-{datetime.date.today().year}, Qiskit Development Team"
@@ -39,7 +43,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.doctest",
     # This is used by qiskit/documentation to generate links to github.com.
-    "sphinx.ext.viewcode",
+    "sphinx.ext.linkcode",
     "matplotlib.sphinxext.plot_directive",
     "reno.sphinxext",
     "sphinxcontrib.katex",
@@ -155,3 +159,43 @@
 # ----------------------------------------------------------------------------------
 
 plot_html_show_formats = False
+
+
+# ----------------------------------------------------------------------------------
+# Source code links
+# ----------------------------------------------------------------------------------
+
+def linkcode_resolve(domain, info):
+    if domain != "py":
+        return None
+
+    module_name = info["module"]
+    module = importlib.import_module(module_name)
+    if module is None or "qiskit" not in module_name:
+        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
+    file_name = full_file_name.split("/qiskit/")[-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}"
+
+    github_branch = os.environ.get("QISKIT_DOCS_GITHUB_BRANCH_NAME", "main")
+    return f"https://github.com/Qiskit/qiskit/tree/{github_branch}/qiskit/{file_name}{linespec}"

tox.ini

@@ -15,7 +15,15 @@ setenv =
   QISKIT_SUPRESS_PACKAGING_WARNINGS=Y
   QISKIT_TEST_CAPTURE_STREAMS=1
   QISKIT_PARALLEL=FALSE
-passenv = RAYON_NUM_THREADS, OMP_NUM_THREADS, QISKIT_PARALLEL, RUST_BACKTRACE, SETUPTOOLS_ENABLE_FEATURES, QISKIT_TESTS, QISKIT_IN_PARALLEL
+passenv = 
+  RAYON_NUM_THREADS
+  OMP_NUM_THREADS
+  QISKIT_PARALLEL
+  RUST_BACKTRACE
+  SETUPTOOLS_ENABLE_FEATURES
+  QISKIT_TESTS
+  QISKIT_IN_PARALLEL
+  QISKIT_DOCS_GITHUB_BRANCH_NAME
 deps =
     setuptools_rust  # This is work around for the bug of tox 3 (see #8606 for more details.)
     -r{toxinidir}/requirements.txt