Fix most Sphinx warnings (#1737)

<!--
⚠️ If you do not respect this template, your pull request will be closed.
⚠️ Your pull request title should be short detailed and understandable for all.
⚠️ Also, please add it in the CHANGELOG file under Unreleased section.
⚠️ If your pull request fixes an open issue, please link to the issue.

✅ I have added the tests to cover my changes.
✅ I have updated the documentation accordingly.
✅ I have read the CONTRIBUTING document.
-->

Fixes the majority of docs failures, which are broadly these categories:

* Invalid references
* Invalid Sphinx syntax
* Config out of sync with qiskit-terra, e.g. missing doctest and qasm3 requirements.

We can't yet enable `sphinx-build -W` because there are some bigger issues still:

* Stop using `sphinx-redirects`: #1738
* Fix an issue in the qiskit-tutorials repo, which should also be setting `-W` in its CI.

.github/workflows/main.yml

@@ -27,10 +27,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
-      - name: Set up Python 3.7
+      - name: Set up Python 3.8
         uses: actions/setup-python@v2
         with:
-          python-version: 3.7
+          python-version: 3.8
       - name: Install Deps
         run: python -m pip install -U 'tox<4'
       - name: Run lint
@@ -42,10 +42,10 @@ jobs:
       - uses: actions/checkout@v2
         with:
           fetch-depth: 0
-      - name: Set up Python 3.7
+      - name: Set up Python 3.8
         uses: actions/setup-python@v2
         with:
-          python-version: 3.7
+          python-version: 3.8
       - name: Install ubuntu Deps
         run: sudo apt-get install -y pandoc graphviz
       - name: Install python Deps
@@ -70,10 +70,10 @@ jobs:
       - uses: actions/checkout@v2
         with:
           fetch-depth: 0
-      - name: Set up Python 3.7
+      - name: Set up Python 3.8
         uses: actions/setup-python@v2
         with:
-          python-version: 3.7
+          python-version: 3.8
       - name: Install python Deps
         run: python -m pip install -U 'tox<4'
       - name: Setup tutorials

constraints.txt

@@ -4,11 +4,6 @@ cryptography==39.0.1
 decorator==4.4.2
 docutils==0.16
 
-# Jinja2 3.1.0 is incompatible with sphinx and/or jupyter until they are updated
-# to work with the new jinja version (the jinja maintainers aren't going to
-# fix things) pin to the previous working version.
-jinja2==3.0.3
-
 # importlib_metadata 5.0 is broken with stevedore, so pin to the last
 # functional version in the 4.x series.
 importlib_metadata<5.0

docs/conf.py

@@ -22,6 +22,8 @@
 import os
 import sys
 
+import sphinx.ext.doctest
+
 sys.path.insert(0, os.path.abspath("."))
 
 import custom_extensions
@@ -52,12 +54,12 @@
     "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",
     "sphinx.ext.extlinks",
-    "jupyter_sphinx",
     "nbsphinx",
     "sphinx_design",
     "sphinx_reredirects",
     "matplotlib.sphinxext.plot_directive",
     "qiskit_sphinx_theme",
+    "sphinx.ext.doctest",
 ]
 
 redirects = url_redirects.determine_redirects()
@@ -158,6 +160,21 @@
 autosummary_generate_overwrite = False
 autoclass_content = "both"
 
+# The pulse library contains some names that differ only in capitalisation, during the changeover
+# surrounding SymbolPulse.  Since these resolve to autosummary filenames that also differ only in
+# capitalisation, this causes problems when the documentation is built on an OS/filesystem that is
+# enforcing case-insensitive semantics.  This setting defines some custom names to prevent the clash
+# from happening.
+autosummary_filename_map = {
+    "qiskit.pulse.library.Constant": "qiskit.pulse.library.Constant_class.rst",
+    "qiskit.pulse.library.Sawtooth": "qiskit.pulse.library.Sawtooth_class.rst",
+    "qiskit.pulse.library.Triangle": "qiskit.pulse.library.Triangle_class.rst",
+    "qiskit.pulse.library.Cos": "qiskit.pulse.library.Cos_class.rst",
+    "qiskit.pulse.library.Sin": "qiskit.pulse.library.Sin_class.rst",
+    "qiskit.pulse.library.Gaussian": "qiskit.pulse.library.Gaussian_class.rst",
+    "qiskit.pulse.library.Drag": "qiskit.pulse.library.Drag_class.rst",
+}
+
 # Move type hints from signatures to the parameter descriptions (except in overload cases, where
 # that's not possible).
 autodoc_typehints = "description"
@@ -170,6 +187,22 @@
 
 plot_html_show_formats = False
 
+# ---------------------------------------------------------------------------
+# Doctest
+# ---------------------------------------------------------------------------
+
+# This option will make doctest ignore whitespace when testing code.
+# It's specially important for circuit representation as it gives an
+# error otherwise
+doctest_default_flags = sphinx.ext.doctest.doctest.NORMALIZE_WHITESPACE
+
+# Leaving this string empty disables testing of doctest blocks from docstrings.
+# Doctest blocks are structures like this one:
+# >> code
+# output
+doctest_test_doctest_blocks = ""
+
+
 # -- Extension configuration -------------------------------------------------
 
 

docs/deprecation_policy.rst

@@ -118,7 +118,7 @@ change:
   keyword argument, or add a second function that only accepts the new form.
 
 
-.. issuing-deprecation-warnings:
+.. _issuing-deprecation-warnings:
 
 Issuing deprecation warnings
 ============================
@@ -152,7 +152,7 @@ other than ``2``, but can be useful if you use a helper function to issue the
 same warning in multiple places.
 
 
-.. testing-deprecated-functionality:
+.. _testing-deprecated-functionality:
 
 Testing deprecated functionality
 ================================

docs/getting_started.rst

@@ -117,12 +117,6 @@ going to run and install the packages.  There are three main ways to do this:
        element or component usually include new features and changes, they generally
        require using the ``development`` version of the rest of the items as well.
 
-       .. note::
-
-       The Terra and Aer packages both require a compiler to build from source before
-       you can install. Ignis, Aqua, and the IBM Quantum Provider backend
-       do not require a compiler.
-
        Installing elements from source requires the following order of installation to
        prevent installing versions of elements that may be lower than those desired if the
        ``pip`` version is behind the source versions:
@@ -133,6 +127,12 @@ going to run and install the packages.  There are three main ways to do this:
        To work with several components and elements simultaneously, use the following
        steps for each element.
 
+       .. note::
+
+          The Terra and Aer packages both require a compiler to build from source before
+          you can install. Ignis, Aqua, and the IBM Quantum Provider backend
+          do not require a compiler.
+
        .. note::
 
           Due to the use of namespace packaging in Python, care must be taken in how you
@@ -337,7 +337,7 @@ going to run and install the packages.  There are three main ways to do this:
              python ./setup.py bdist_wheel
 
           If you need to set a custom option during the wheel build, refer to
-          :ref:`aer_wheel_build_options`.
+          :ref:`Custom options <aer_wheel_build_options>`.
 
           After you build the Python wheel, it will be stored in the ``dist/`` dir in the
           Aer repository. The exact version will depend

docs/maintainers_guide.rst

@@ -256,17 +256,24 @@ The module-level docstring
       =======================================
       DAG Circuits (:mod:`qiskit.dagcircuit`)
       =======================================
+
       .. currentmodule:: qiskit.dagcircuit
+
       DAG Circuits
       ============
+
       .. autosummary::
          :toctree: ../stubs/
+
          DAGCircuit
          DAGNode
+
       Exceptions
       ==========
+
       .. autosummary::
          :toctree: ../stubs/
+
          DAGCircuitError
       """
 

docs/release_notes.rst

@@ -2877,7 +2877,7 @@ New Features
 
 .. releasenotes/notes/0.23/add-sparsepauliop-based-z2symetries-1811e956c232f664.yaml @ b'5d6ba50234a45e461ac65eed5b98a58ffb1f5be7'
 
-- Added a new class :class:`~.Z2Symmetries` to :mod:`qiskit.quantum_info`
+- Added a new class :class:`~qiskit.quantum_info.Z2Symmetries` to :mod:`qiskit.quantum_info`
   which is used to identify any :math:`Z_2` symmetries from an input
   :class:`~.SparsePauliOp`.
 
@@ -4182,7 +4182,8 @@ Bug Fixes
 .. releasenotes/notes/0.23/fix-ae-algorithms-1c0a43c596766cb3.yaml @ b'5d6ba50234a45e461ac65eed5b98a58ffb1f5be7'
 
 - Fixed an issue with  the amplitude estimation algorithms in the
-  ``qiskit.algorithms.amplitude_estimators`` module (see :ref:`amplitude_estimators`) for
+  ``qiskit.algorithms.amplitude_estimators`` module (see
+  :mod:`~qiskit.algorithms.amplitude_estimators`) for
   the usage with primitives built from the abstract :class:`.BaseSampler` primitive (such
   as :class:`~.Sampler` and :class:`~.BackendSampler`). Previously, the measurement
   results were expanded to more bits than actually measured which for oracles with more
@@ -5831,12 +5832,12 @@ New Features
 
 .. releasenotes/notes/0.22/implements_two_step_tapering-f481a8cac3990cd5.yaml @ b'618770367f7a5a3a22fd43ea9fcfb7f17393eb6a'
 
-- The :class:`~.Z2Symmetries` class has two new methods,
-  :meth:`~.Z2Symmetries.convert_clifford` and
-  :meth:`~.Z2Symmetries.taper_clifford`. These two methods are the two
+- The :class:`~qiskit.opflow.primitive_ops.Z2Symmetries` class has two new methods,
+  :meth:`~qiskit.opflow.primitive_ops.Z2Symmetries.convert_clifford` and
+  :meth:`~qiskit.opflow.primitive_ops.Z2Symmetries.taper_clifford`. These two methods are the two
   operations necessary for taperng an operator based on the Z2 symmetries
   in the object and were previously performed internally via the
-  :meth:`~.Z2Symmetries.taper` method. However, these methods are now
+  :meth:`~qiskit.opflow.primitive_ops.Z2Symmetries.taper` method. However, these methods are now
   public methods of the class which can be called individually if needed.
 
 .. releasenotes/notes/0.22/improve-basepauli-evolve-clifford-d714b2eee475334b.yaml @ b'618770367f7a5a3a22fd43ea9fcfb7f17393eb6a'
@@ -7569,7 +7570,7 @@ Bug Fixes
 
 .. releasenotes/notes/taper-performance-6da355c04da5b648.yaml @ b'fdb62bea1eac6822b96e8dcd2fe19e7aee10027e'
 
-- Fixed support for running :meth:`.Z2Symmetries.taper` on larger problems.
+- Fixed support for running ``Z2Symmetries.taper()`` on larger problems.
   Previously, the method would require a large amount of memory which would
   typically cause failures for larger problem. As a side effect of this fix
   the performance has significantly improved.
@@ -8883,7 +8884,7 @@ Bug Fixes
 
 .. releasenotes/notes/fix-hard-coded-sleep-run-circuits-a1588164e61d5336.yaml @ b'625b202a4dd0c223579dca44eec530b8a0813d76'
 
-- The :class:`~qiskit.utils.QuantumInstance` class used by many algorithms (like :class:`~.VQE`)
+- The :class:`~qiskit.utils.QuantumInstance` class used by many algorithms (like ``VQE``)
   was hard-coding the value for a sleep while it looped waiting for the job status to be updated.
   It now respects the configured sleep value as set per the ``wait`` attribute in the
   initializer of :class:`~qiskit.utils.QuantumInstance`.
@@ -11852,11 +11853,11 @@ Bug Fixes
   order of :attr:`~qiskit.circuit.QuantumCircuit.parameters` could be
   incorrect.
 
-  To fix this issue a new QPY format version, :ref:`version_3`, was required.
+  To fix this issue a new QPY format version, :ref:`qpy_version_3`, was required.
   This new format version includes a representation of the
   :class:`~qiskit.circuit.ParameterVectorElement` class which is
   described in the :mod:`~qiskit.circuit.qpy_serialization` documentation at
-  :ref:`param_vector`.
+  :ref:`qpy_param_vector`.
 
 .. releasenotes/notes/fix-pauli-evolution-gate-bf85592f0f8f0ba7.yaml @ b'73024df2f62b0f8c9fd2e439a7bbeba2d8b0aaa9'
 
@@ -11876,7 +11877,7 @@ Bug Fixes
   available from :mod:`qiskit.synthesis` can be used with a
   :class:`~qiskit.circuit.library.PauliEvolutionGate` for qpy serialization.
 
-  To fix this issue a new QPY format version, :ref:`version_3`, was required.
+  To fix this issue a new QPY format version, :ref:`qpy_version_3`, was required.
   This new format version includes a representation of the
   :class:`~qiskit.circuit.library.PauliEvolutionGate` class which is
   described in the :mod:`~qiskit.circuit.qpy_serialization` documentation at
@@ -12237,8 +12238,10 @@ New Features
 
 - Every attribute of the :class:`~qiskit.algorithms.VQE` class that is set at
   the initialization is now accessible with getters and setters. Further, the
-  default values of the VQE attributes :attr:`~.VQE.ansatz` and
-  :attr:`~.VQE.optimizer` can be reset by assigning ``None`` to them::
+  default values of the VQE attributes
+  :attr:`~qiskit.algorithms.minimimum_eigen_solvers.VQE.ansatz` and
+  :attr:`~qiskit.algorithms.minimimum_eigen_solvers.VQE.optimizer` can be
+  reset by assigning ``None`` to them::
 
       vqe = VQE(my_ansatz, my_optimizer)
       vqe.ansatz = None   # reset to default: RealAmplitudes ansatz
@@ -12971,7 +12974,7 @@ New Features
   QPY would only accept a :attr:`~qiskit.circuit.QuantumCircuit.global_phase`
   that was a ``float``.
 
-  This requires the QPY format :ref:`version_2` which was introduced in
+  This requires the QPY format :ref:`qpy_version_2` which was introduced in
   this release to represent the additional types.
 
 .. releasenotes/notes/0.19/quantumcircuit-consolidate-bit_indices-c4ee90e831f1aed2.yaml @ b'd5094eeca27f2c0f3c13f23f1e812cd41b6108f2'
@@ -13178,9 +13181,11 @@ New Features
 
 .. releasenotes/notes/0.19/support-dict-for-aux-operators-c3c9ad380c208afd.yaml @ b'd5094eeca27f2c0f3c13f23f1e812cd41b6108f2'
 
-- The :obj:`.Eigensolver` and :obj:`.MinimumEigensolver` interfaces now support the type
+- The :obj:`~qiskit.algorithms.eigen_solvers.Eigensolver` and
+  :obj:`~qiskit.algorithms.minimimum_eigen_solvers.MinimumEigensolver` interfaces now support the type
   ``Dict[str, Optional[OperatorBase]]`` for the ``aux_operators`` parameter in their respective
-  :meth:`~.Eigensolver.compute_eigenvalues` and :meth:`~.MinimumEigensolver.compute_minimum_eigenvalue` methods.
+  :meth:`~qiskit.algorithms.eigen_solvers.Eigensolver.compute_eigenvalues` and
+  :meth:`~qiskit.algorithms.minimimum_eigen_solvers.MinimumEigensolver.compute_minimum_eigenvalue` methods.
   In this case, the auxiliary eigenvalues are also stored in a dictionary under the same keys
   provided by the ``aux_operators`` dictionary. Keys that correspond to an operator that does not commute
   with the main operator are dropped.
@@ -14425,7 +14430,8 @@ Bug Fixes
 
 - When tapering an empty zero operator in :mod:`qiskit.opflow`, the code, on detecting it was zero, logged a
   warning and returned the original operator.  Such operators are commonly found in
-  the auxiliary operators, when using Qiskit Nature, and the above behavior caused :obj:`.VQE`
+  the auxiliary operators, when using Qiskit Nature, and the above behavior caused
+  :obj:`~qiskit.algorithms.minimimum_eigen_solvers.VQE`
   to throw an exception as tapered non-zero operators were a different number of qubits
   from the tapered zero operators (since taper has returned the input operator unchanged).
   The code will now correctly taper a zero operator such that the number of qubits is
@@ -14966,9 +14972,7 @@ New Features
   (eg. ``ThreadPoolExecutor``, ``ProcessPoolExecutor``), and
   `Dask <http://dask.org>`__ distributed  Client executors if the optional
   dask library is installed. Using a Dask executor allows configuring parallel
-  execution of multiple circuits on HPC clusters. See the
-  Dask executor :ref:`API Documentation <dask>` for additional details
-  on using Dask executors for HPC simulation.
+  execution of multiple circuits on HPC clusters.
 
 - Adds ability to record logging data for the ``matrix_product_state``
   simulation method to the experiment result metadata by setting the
@@ -17347,8 +17351,8 @@ rest of the Qiskit metapackage as optional extras (e.g.
 The core algorithms and the operator flow now exist as part of qiskit-terra at
 :mod:`qiskit.algorithms` and :mod:`qiskit.opflow`. Depending on your existing
 usage of Aqua you should either use the application packages or the new modules
-in Qiskit Terra. For more details on how to migrate from Qiskit Aqua you can
-refer to the :ref:`aqua-migration`.
+in Qiskit Terra. For more details on how to migrate from Qiskit Aqua, you can
+refer to the `migration guide <https://github.com/Qiskit/qiskit-aqua/blob/main/README.md#migration-guide>`_.
 
 .. _Release Notes_0.17.0:
 
@@ -18125,15 +18129,16 @@ New Features
   provided by the :mod:`qiskit.aqua.algorithms` module (which is now
   deprecated) and provides the building blocks for constructing quantum
   algorithms. For details on migrating from ``qiskit-aqua`` to this new
-  module please refer to the migration guide :ref:`aqua-migration`
+  module, please refer to the
+  `migration guide <https://github.com/Qiskit/qiskit-aqua/blob/main/README.md#migration-guide>`_.
 
 - A new module :mod:`qiskit.opflow` has been introduced. This module
   contains functionality equivalent to what has previously been
   provided by the :mod:`qiskit.aqua.operators` module (which is now
   deprecated) and provides the operators and state functions which are
   used to build quantum algorithms. For details on migrating from
-  ``qiskit-aqua`` to this new module please refer to the migration guide
-  :ref:`aqua-migration`
+  ``qiskit-aqua`` to this new module, please refer to the
+  `migration guide <https://github.com/Qiskit/qiskit-aqua/blob/main/README.md#migration-guide>`_.
 
 - This is the first release that includes precompiled binary wheels for
   the for Linux aarch64 systems. If you are running a manylinux2014
@@ -20058,8 +20063,8 @@ operator flow now exist as part of qiskit-terra at :mod:`qiskit.algorithms` and
 :mod:`qiskit.opflow`. Depending on your existing usage of Aqua you should either
 use the application packages or the new modules in Qiskit Terra.
 
-For more details on how to migrate from using Qiskit Aqua you can refer to the
-:ref:`aqua-migration`.
+For more details on how to migrate from using Qiskit Aqua, you can refer to the
+`migration guide <https://github.com/Qiskit/qiskit-aqua/blob/main/README.md#migration-guide>`_.
 
 IBM Q Provider 0.12.2
 =====================

requirements-dev.txt

@@ -5,7 +5,6 @@ qiskit-sphinx-theme~=1.11.0
 pylatexenc>=1.4
 sphinx-automodapi
 jupyter
-jupyter-sphinx
 sphinx-design
 matplotlib>=3.3.0
 pydot
@@ -16,6 +15,7 @@ nbsphinx
 cvxpy
 networkx>=2.3
 sphinx-reredirects
+qiskit-qasm3-import; python_version>'3.7'
 
 # Dev tooling
 black~=23.3