Merge branch 'Qiskit:main' into move-target

.github/workflows/docs_deploy.yml

@@ -29,9 +29,21 @@ jobs:
       - name: Install dependencies
         run: tools/install_ubuntu_docs_dependencies.sh
 
+      - name: Determine GitHub branch name
+        run: |
+          # Tags like 1.0.0 and 1.0.0rc1 should point to their stable branch. We do this
+          # to reduce the diff in the qiskit/documentation repository between generating
+          # the API docs from a tag release versus a workflow_dispatch.
+          if [[ $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:

README.md

@@ -20,6 +20,9 @@ For more details on how to use Qiskit, refer to the documentation located here:
 
 ## Installation
 
+> [!WARNING]
+> Do not try to upgrade an existing Qiskit 0.* environment to Qiskit 1.0 in-place. [Read more](https://docs.quantum.ibm.com/api/migration-guides/qiskit-1.0-installation).
+
 We encourage installing Qiskit via ``pip``:
 
 ```bash

docs/conf.py

@@ -18,6 +18,12 @@
 
 import datetime
 import doctest
+import importlib
+import inspect
+import os
+import re
+from pathlib import Path
+
 
 project = "Qiskit"
 project_copyright = f"2017-{datetime.date.today().year}, Qiskit Development Team"
@@ -39,7 +45,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 +161,54 @@
 # ----------------------------------------------------------------------------------
 
 plot_html_show_formats = False
+
+
+# ----------------------------------------------------------------------------------
+# Source code links
+# ----------------------------------------------------------------------------------
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+
+def linkcode_resolve(domain, info):
+    if domain != "py":
+        return None
+
+    module_name = info["module"]
+    if "qiskit" 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}"
+
+    github_branch = os.environ.get("QISKIT_DOCS_GITHUB_BRANCH_NAME", "main")
+    return f"https://github.com/Qiskit/qiskit/tree/{github_branch}/{file_name}{linespec}"