From 0f0c7185ed5b992a53bae37e2e8a67b6d2630d44 Mon Sep 17 00:00:00 2001
From: Jake Lishman <jake.lishman@ibm.com>
Date: Mon, 24 Jan 2022 15:27:31 +0000
Subject: [PATCH] Add intersphinx configuration for core Qiskit components

This makes it possible to link to documentation in the core Qiskit
components (Terra, Aer and IBMQ Provider) using regular Sphinx
references.
---
 docs/_ext/custom_styles/styles.py                        | 9 +++++----
 docs/conf.py                                             | 6 +++++-
 qiskit_experiments/database_service/__init__.py          | 4 ++--
 .../library/quantum_volume/qv_experiment.py              | 9 ++++-----
 4 files changed, 16 insertions(+), 12 deletions(-)

diff --git a/docs/_ext/custom_styles/styles.py b/docs/_ext/custom_styles/styles.py
index 9127ff4fc9..adbc5f9b55 100644
--- a/docs/_ext/custom_styles/styles.py
+++ b/docs/_ext/custom_styles/styles.py
@@ -212,8 +212,8 @@ def _extra_sections(self, sectioned_docstring: Dict[str, List[str]]):
         # add transpiler option
         transpiler_option_desc = [
             "This option is used for circuit optimization. ",
-            "See `Qiskit Transpiler <https://qiskit.org/documentation/stubs/",
-            "qiskit.compiler.transpile.html>`_ documentation for available options.",
+            "See the documentation of :func:`qiskit.transpile <qiskit.compiler.transpile>` "
+            "for available options.",
             "",
         ]
         transpiler_option_desc.extend(
@@ -230,8 +230,9 @@ def _extra_sections(self, sectioned_docstring: Dict[str, List[str]]):
             "This option is used for controlling job execution condition. "
             "Note that this option is provider dependent. "
             "See provider's backend runner API for available options. "
-            "See `here <https://qiskit.org/documentation/stubs/qiskit.providers.ibmq.",
-            "IBMQBackend.html#qiskit.providers.ibmq.IBMQBackend.run>`_ for IBM Quantum Service.",
+            "See the documentation of "
+            ":meth:`IBMQBackend.run <qiskit.providers.ibmq.IBMQBackend.run>` "
+            "for the IBM Quantum Service.",
             "",
         ]
         run_option_desc.extend(
diff --git a/docs/conf.py b/docs/conf.py
index 44ad860300..78dd735219 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -182,7 +182,11 @@
 }
 
 autoclass_content = 'both'
-intersphinx_mapping = {'matplotlib': ('https://matplotlib.org/stable/', None)}
+intersphinx_mapping = {
+    'matplotlib': ('https://matplotlib.org/stable/', None),
+    'qiskit': ('https://qiskit.org/documentation/', None),
+}
+
 # Current scipy hosted docs are missing the object.inv file so leaving this
 # commented out until the missing file is added back.
 #                       'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None)}
diff --git a/qiskit_experiments/database_service/__init__.py b/qiskit_experiments/database_service/__init__.py
index 4ee59e18b0..4049c7d748 100644
--- a/qiskit_experiments/database_service/__init__.py
+++ b/qiskit_experiments/database_service/__init__.py
@@ -61,8 +61,8 @@ class only for convenience.
 example, to retrieve a saved analysis result.
 
 Currently only IBM Quantum provides this database service. See
-`qiskit-ibmq-provider <https://qiskit.org/documentation/apidoc/ibmq_experiment.html>`_
-for more details.
+the :mod:`Experiment <qiskit.providers.ibmq.experiment>` module in the IBM
+Quantum provider for more details.
 
 Classes
 =======
diff --git a/qiskit_experiments/library/quantum_volume/qv_experiment.py b/qiskit_experiments/library/quantum_volume/qv_experiment.py
index 06a5b00713..353e004afc 100644
--- a/qiskit_experiments/library/quantum_volume/qv_experiment.py
+++ b/qiskit_experiments/library/quantum_volume/qv_experiment.py
@@ -49,12 +49,11 @@ class QuantumVolume(BaseExperiment):
         <https://qiskit.org/textbook/ch-quantum-hardware/measuring-quantum-volume.html>`_
         for an explanation on the QV protocol.
 
-        In the QV experiment we generate `QV circuits
-        <https://qiskit.org/documentation/stubs/qiskit.circuit.library.QuantumVolume.html>`_
-        on :math:`d` qubits, which contain :math:`d` layers, where each layer consists of random 2-qubit
+        In the QV experiment we generate :class:`~qiskit.circuit.library.QuantumVolume` circuits on
+        :math:`d` qubits, which contain :math:`d` layers, where each layer consists of random 2-qubit
         unitary gates from :math:`SU(4)`, followed by a random permutation on the :math:`d` qubits.
-        Then these circuits run on the quantum backend and on an ideal simulator
-        (either :class:`AerSimulator` or :class:`qiskit.quantum_info.Statevector`).
+        Then these circuits run on the quantum backend and on an ideal simulator (either
+        :class:`~qiskit.providers.aer.AerSimulator` or :class:`~qiskit.quantum_info.Statevector`).
 
         A depth :math:`d` QV circuit is successful if it has 'mean heavy-output probability' > 2/3 with
         confidence level > 0.977 (corresponding to z_value = 2), and at least 100 trials have been ran.