Fix documentation for Sphinx 4 (Qiskit#7469)

Sphinx 4 is more particular about disallowing the same Python object to be documented in multiple toctree entries. The culprits were `Barrier`, `Reset` and `Measure` in the circuit library; the library re-exports them from their canonical locations, and used `autosummary` to generate extra links to them. We still re-export them, but change the `autosummary` tables to link to the existing definitions. This then builds the documentation without errors on Sphinx 4, and consequently the pin on `sphinx-panels` can be removed. Previously the pin was applied because an update to that package caused the documentation build to break; in reality, it's just that `sphinx-panels<0.6` pinned itself to `Sphinx<4`, whereas version 0.6 allowed Sphinx 4 - there were no breaking changes for us. Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
git-devanand · Jan 4, 2022 · 3092929 · 3092929
1 parent 2867f20
commit 3092929
Show file tree

Hide file tree

Showing 3 changed files with 16 additions and 5 deletions.
diff --git a/qiskit/circuit/__init__.py b/qiskit/circuit/__init__.py
@@ -187,6 +187,7 @@
    Gate
    ControlledGate
    Delay
+   Barrier
    Measure
    Reset
    Instruction

diff --git a/qiskit/circuit/library/__init__.py b/qiskit/circuit/library/__init__.py
@@ -24,7 +24,6 @@
    :toctree: ../stubs/
    :template: autosummary/class_no_inherited_members.rst
 
-   Barrier
    C3XGate
    C3SXGate
    C4XGate
@@ -50,12 +49,10 @@
    MCXGrayCode
    MCXRecursive
    MCXVChain
-   Measure
    MSGate
    PhaseGate
    RCCXGate
    RC3XGate
-   Reset
    RGate
    RXGate
    RXXGate
@@ -82,6 +79,19 @@
    YGate
    ZGate
 
+Standard Directives
+===================
+
+..
+    This summary table deliberately does not generate toctree entries; these directives are "owned"
+    by ``qiskit.circuit``.
+
+.. autosummary::
+
+   ~qiskit.circuit.Barrier
+   ~qiskit.circuit.Measure
+   ~qiskit.circuit.Reset
+
 Generalized Gates
 =================
 

diff --git a/requirements-dev.txt b/requirements-dev.txt
@@ -18,11 +18,11 @@ pylatexenc>=1.4
 ddt>=1.2.0,!=1.4.0,!=1.4.3
 seaborn>=0.9.0
 reno>=3.4.0
-Sphinx>=3.0.0,<4.0.0
+Sphinx>=3.0.0
 qiskit-sphinx-theme>=1.6
 sphinx-autodoc-typehints
 jupyter-sphinx
-sphinx-panels<0.6.0
+sphinx-panels
 pygments>=2.4
 networkx>=2.2
 scikit-learn>=0.20.0
-Original file line number
+Diff line change
@@ Expand Up / @@ -187,6 +187,7 @@ @@
        Gate
        ControlledGate
        Delay
+       Barrier
        Measure
        Reset
        Instruction
@@ Expand Down @@