Document functions on module pages (#10471)

* Document functions on module pages

* Fix invalid functions

* Revert visualization because each function is so big

* Fix more issues

* Use currentmodule

* Show modules & fix recursion

* Add some missing autofunctions

---------

Co-authored-by: Jake Lishman <jake.lishman@ibm.com>
(cherry picked from commit 025320f)

docs/conf.py

@@ -57,8 +57,13 @@
 
 pygments_style = "colorful"
 
-# Whether module names are included in crossrefs of functions, classes, etc.
-add_module_names = False
+# This adds the module name to e.g. function API docs. We use the default of True because our
+# module pages sometimes have functions from submodules on the page, and we want to make clear
+# that you must include the submodule to import it. We should strongly consider reorganizing our
+# code to avoid this, i.e. re-exporting the submodule members from the top-level module. Once fixed
+# and verified by only having a single `.. currentmodule::` in the file, we can turn this back to
+# False.
+add_module_names = True
 
 # A list of prefixes that are ignored for sorting the Python module index
 # (e.g., if this is set to ['foo.'], then foo.bar is shown under B, not F).

qiskit/algorithms/__init__.py

@@ -280,23 +280,7 @@
 Exceptions
 ----------
 
-.. autosummary::
-   :toctree: ../stubs/
-
-   AlgorithmError
-
-
-Utility methods
----------------
-
-Utility methods used by algorithms.
-
-.. autosummary::
-   :toctree: ../stubs/
-
-   eval_observables
-   estimate_observables
-
+.. autoexception:: AlgorithmError
 
 Utility classes
 ---------------
@@ -308,6 +292,14 @@
 
    AlgorithmJob
 
+Utility functions
+-----------------
+
+Utility functions used by algorithms.
+
+.. autofunction:: eval_observables
+.. autofunction:: estimate_observables
+
 """
 import warnings
 

qiskit/assembler/__init__.py

@@ -20,26 +20,17 @@
 Circuit Assembler
 =================
 
-.. autosummary::
-   :toctree: ../stubs/
-
-   assemble_circuits
+.. autofunction:: assemble_circuits
 
 Schedule Assembler
 ==================
 
-.. autosummary::
-   :toctree: ../stubs/
-
-   assemble_schedules
+.. autofunction:: assemble_schedules
 
 Disassembler
 ============
 
-.. autosummary::
-   :toctree: ../stubs/
-
-   disassemble
+.. autofunction:: disassemble
 
 RunConfig
 =========

qiskit/circuit/__init__.py

@@ -345,10 +345,9 @@
 Random Circuits
 ---------------
 
-.. autosummary::
-   :toctree: ../stubs/
-
-   random.random_circuit
+.. currentmodule:: qiskit.circuit.random
+.. autofunction:: random_circuit
+.. currentmodule:: qiskit.circuit
 """
 from .quantumcircuit import QuantumCircuit
 from .classicalregister import ClassicalRegister, Clbit

qiskit/circuit/library/__init__.py

@@ -394,98 +394,91 @@
 Techniques for the synthesis of reversible Toffoli networks, 2007
 http://dx.doi.org/10.1145/1278349.1278355
 
-.. autosummary::
-   :toctree: ../stubs/
-
-   templates.nct.template_nct_2a_1
-   templates.nct.template_nct_2a_2
-   templates.nct.template_nct_2a_3
-   templates.nct.template_nct_4a_1
-   templates.nct.template_nct_4a_2
-   templates.nct.template_nct_4a_3
-   templates.nct.template_nct_4b_1
-   templates.nct.template_nct_4b_2
-   templates.nct.template_nct_5a_1
-   templates.nct.template_nct_5a_2
-   templates.nct.template_nct_5a_3
-   templates.nct.template_nct_5a_4
-   templates.nct.template_nct_6a_1
-   templates.nct.template_nct_6a_2
-   templates.nct.template_nct_6a_3
-   templates.nct.template_nct_6a_4
-   templates.nct.template_nct_6b_1
-   templates.nct.template_nct_6b_2
-   templates.nct.template_nct_6c_1
-   templates.nct.template_nct_7a_1
-   templates.nct.template_nct_7b_1
-   templates.nct.template_nct_7c_1
-   templates.nct.template_nct_7d_1
-   templates.nct.template_nct_7e_1
-   templates.nct.template_nct_9a_1
-   templates.nct.template_nct_9c_1
-   templates.nct.template_nct_9c_2
-   templates.nct.template_nct_9c_3
-   templates.nct.template_nct_9c_4
-   templates.nct.template_nct_9c_5
-   templates.nct.template_nct_9c_6
-   templates.nct.template_nct_9c_7
-   templates.nct.template_nct_9c_8
-   templates.nct.template_nct_9c_9
-   templates.nct.template_nct_9c_10
-   templates.nct.template_nct_9c_11
-   templates.nct.template_nct_9c_12
-   templates.nct.template_nct_9d_1
-   templates.nct.template_nct_9d_2
-   templates.nct.template_nct_9d_3
-   templates.nct.template_nct_9d_4
-   templates.nct.template_nct_9d_5
-   templates.nct.template_nct_9d_6
-   templates.nct.template_nct_9d_7
-   templates.nct.template_nct_9d_8
-   templates.nct.template_nct_9d_9
-   templates.nct.template_nct_9d_10
+.. currentmodule:: qiskit.circuit.library.templates.nct
+.. autofunction:: template_nct_2a_1
+.. autofunction:: template_nct_2a_2
+.. autofunction:: template_nct_2a_3
+.. autofunction:: template_nct_4a_1
+.. autofunction:: template_nct_4a_2
+.. autofunction:: template_nct_4a_3
+.. autofunction:: template_nct_4b_1
+.. autofunction:: template_nct_4b_2
+.. autofunction:: template_nct_5a_1
+.. autofunction:: template_nct_5a_2
+.. autofunction:: template_nct_5a_3
+.. autofunction:: template_nct_5a_4
+.. autofunction:: template_nct_6a_1
+.. autofunction:: template_nct_6a_2
+.. autofunction:: template_nct_6a_3
+.. autofunction:: template_nct_6a_4
+.. autofunction:: template_nct_6b_1
+.. autofunction:: template_nct_6b_2
+.. autofunction:: template_nct_6c_1
+.. autofunction:: template_nct_7a_1
+.. autofunction:: template_nct_7b_1
+.. autofunction:: template_nct_7c_1
+.. autofunction:: template_nct_7d_1
+.. autofunction:: template_nct_7e_1
+.. autofunction:: template_nct_9a_1
+.. autofunction:: template_nct_9c_1
+.. autofunction:: template_nct_9c_2
+.. autofunction:: template_nct_9c_3
+.. autofunction:: template_nct_9c_4
+.. autofunction:: template_nct_9c_5
+.. autofunction:: template_nct_9c_6
+.. autofunction:: template_nct_9c_7
+.. autofunction:: template_nct_9c_8
+.. autofunction:: template_nct_9c_9
+.. autofunction:: template_nct_9c_10
+.. autofunction:: template_nct_9c_11
+.. autofunction:: template_nct_9c_12
+.. autofunction:: template_nct_9d_1
+.. autofunction:: template_nct_9d_2
+.. autofunction:: template_nct_9d_3
+.. autofunction:: template_nct_9d_4
+.. autofunction:: template_nct_9d_5
+.. autofunction:: template_nct_9d_6
+.. autofunction:: template_nct_9d_7
+.. autofunction:: template_nct_9d_8
+.. autofunction:: template_nct_9d_9
+.. autofunction:: template_nct_9d_10
+.. currentmodule:: qiskit.circuit.library
 
 Clifford template circuits
 --------------------------
 
 Template circuits over Clifford gates.
 
-.. autosummary::
-   :toctree: ../stubs/
-
-   clifford_2_1
-   clifford_2_2
-   clifford_2_3
-   clifford_2_4
-   clifford_3_1
-   clifford_4_1
-   clifford_4_2
-   clifford_4_3
-   clifford_4_4
-   clifford_5_1
-   clifford_6_1
-   clifford_6_2
-   clifford_6_3
-   clifford_6_4
-   clifford_6_5
-   clifford_8_1
-   clifford_8_2
-   clifford_8_3
+.. autofunction:: clifford_2_1
+.. autofunction:: clifford_2_2
+.. autofunction:: clifford_2_3
+.. autofunction:: clifford_2_4
+.. autofunction:: clifford_3_1
+.. autofunction:: clifford_4_1
+.. autofunction:: clifford_4_2
+.. autofunction:: clifford_4_3
+.. autofunction:: clifford_4_4
+.. autofunction:: clifford_5_1
+.. autofunction:: clifford_6_1
+.. autofunction:: clifford_6_2
+.. autofunction:: clifford_6_3
+.. autofunction:: clifford_6_4
+.. autofunction:: clifford_6_5
+.. autofunction:: clifford_8_1
+.. autofunction:: clifford_8_2
+.. autofunction:: clifford_8_3
 
 RZXGate template circuits
 -------------------------
 
 Template circuits with :class:`~qiskit.circuit.library.RZXGate`.
 
-.. autosummary::
-   :toctree: ../stubs/
-
-   rzx_yz
-   rzx_xz
-   rzx_cy
-   rzx_zz1
-   rzx_zz2
-   rzx_zz3
+.. autofunction:: rzx_yz
+.. autofunction:: rzx_xz
+.. autofunction:: rzx_cy
+.. autofunction:: rzx_zz1
+.. autofunction:: rzx_zz2
+.. autofunction:: rzx_zz3
 
 """
 

qiskit/compiler/__init__.py

@@ -20,13 +20,10 @@
 Circuit and Pulse Compilation Functions
 =======================================
 
-.. autosummary::
-   :toctree: ../stubs/
-
-   assemble
-   schedule
-   transpile
-   sequence
+.. autofunction:: assemble
+.. autofunction:: schedule
+.. autofunction:: transpile
+.. autofunction:: sequence
 
 """
 

qiskit/converters/__init__.py

@@ -17,18 +17,15 @@
 
 .. currentmodule:: qiskit.converters
 
-.. autosummary::
-   :toctree: ../stubs/
-
-   circuit_to_dag
-   dag_to_circuit
-   circuit_to_instruction
-   circuit_to_gate
-   ast_to_dag
-   dagdependency_to_circuit
-   circuit_to_dagdependency
-   dag_to_dagdependency
-   dagdependency_to_dag
+.. autofunction:: circuit_to_dag
+.. autofunction:: dag_to_circuit
+.. autofunction:: circuit_to_instruction
+.. autofunction:: circuit_to_gate
+.. autofunction:: ast_to_dag
+.. autofunction:: dagdependency_to_circuit
+.. autofunction:: circuit_to_dagdependency
+.. autofunction:: dag_to_dagdependency
+.. autofunction:: dagdependency_to_dag
 """
 
 from .circuit_to_dag import circuit_to_dag

qiskit/opflow/__init__.py

@@ -149,21 +149,15 @@
 Utility functions
 =================
 
-.. autosummary::
-   :toctree: ../stubs/
-
-   commutator
-   anti_commutator
-   double_commutator
+.. autofunction:: commutator
+.. autofunction:: anti_commutator
+.. autofunction:: double_commutator
 
 
 Exceptions
 ==========
 
-.. autosummary::
-   :toctree: ../stubs/
-
-   OpflowError
+.. autoexception:: OpflowError
 """
 import warnings
 

qiskit/providers/__init__.py

@@ -125,13 +125,10 @@
 Exceptions
 ----------
 
-.. autosummary::
-   :toctree: ../stubs/
-
-   QiskitBackendNotFoundError
-   BackendPropertyError
-   JobError
-   JobTimeoutError
+.. autoexception:: QiskitBackendNotFoundError
+.. autoexception:: BackendPropertyError
+.. autoexception:: JobError
+.. autoexception:: JobTimeoutError
 
 ======================
 Writing a New Provider

qiskit/pulse/__init__.py

@@ -54,7 +54,7 @@
 Exceptions
 ==========
 
-.. autoclass:: PulseError
+.. autoexception:: PulseError
 """
 
 # Builder imports.