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

.gitignore

@@ -107,3 +107,6 @@ Qconfig.py
 .DS_Store
 
 /docs/stubs/
+
+# Pycharm
+.idea

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,85 @@
 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
+        and "BUILD_SOURCE_BRANCH_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")
+        or os.environ.get("SYSTEM_PULL_REQUEST_TARGET_BRANCH_NAME")
+    ):
+        return base_ref
+
+    ref_name = (
+        os.environ.get("GITHUB_REF_NAME")
+        or os.environ.get("BUILD_SOURCE_BRANCH_NAME")
+    )
+    assert ref_name is not None
+
+    # 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_match = re.match(r"(\d+\.\d+)", ref_name)
+    return (
+        f"stable/{version_without_patch_match.group()}"
+        if version_without_patch_match
+        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" 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:
+        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}"