Reorganize API docs (#698)

Applies changes similar to Qiskit/qiskit-addon-obp#24. Refer to that for more explanation.

This repository is laid out a little differently than how qiskit-addon-obp was, however. This repository was extremely flat: all interfaces were explicitly listed in `index.rst` and there were no module pages. Naturally, no functions/classes were inlined on module pages.

Now, the docs are organized by the distinct modules.

<details><summary>new left ToC for docs.quantum.ibm.com</summary>

<img width="248" alt="Screenshot 2024-10-28 at 2 42 15 PM" src="https://github.com/user-attachments/assets/8eaf20f0-f4c1-4bca-9f5e-97ccc0c95054">
</details>

docs/apidocs/index.rst

@@ -1,26 +1,16 @@
-.. qiskit_addon_cutting:
+======================================
+``qiskit-addon-cutting`` API reference
+======================================
 
-.. module:: qiskit_addon_cutting
+.. toctree::
+   :maxdepth: 1
 
-==============
-API References
-==============
-
-###############
-Circuit Cutting
-###############
-
-.. automodule:: qiskit_addon_cutting
-   :no-index:
-   :no-members:
-   :no-inherited-members:
-   :no-special-members:
-
-#########
-Utilities
-#########
-
-.. automodule:: qiskit_addon_cutting.utils
-   :no-members:
-   :no-inherited-members:
-   :no-special-members:
+   qiskit_addon_cutting
+   qiskit_addon_cutting.instructions
+   qiskit_addon_cutting.qpd
+   qiskit_addon_cutting.utils.bitwise
+   qiskit_addon_cutting.utils.iteration
+   qiskit_addon_cutting.utils.observable_grouping
+   qiskit_addon_cutting.utils.simulation
+   qiskit_addon_cutting.utils.transforms
+   qiskit_addon_cutting.utils.transpiler_passes

docs/apidocs/qiskit_addon_cutting.instructions.rst

@@ -0,0 +1,13 @@
+=======================================================
+Instructions (:mod:`qiskit_addon_cutting.instructions`)
+=======================================================
+
+.. automodule:: qiskit_addon_cutting.instructions
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
+
+.. currentmodule:: qiskit_addon_cutting.instructions
+
+.. autoclass:: CutWire
+.. autoclass:: Move

docs/apidocs/qiskit_addon_cutting.qpd.rst

@@ -0,0 +1,20 @@
+=======================================================================
+Quasi-Probability Decomposition (QPD) (:mod:`qiskit_addon_cutting.qpd`)
+=======================================================================
+
+.. automodule:: qiskit_addon_cutting.qpd
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
+
+.. currentmodule:: qiskit_addon_cutting.qpd
+
+.. autoclass:: QPDBasis
+.. autoclass:: BaseQPDGate
+.. autoclass:: SingleQubitQPDGate
+.. autoclass:: TwoQubitQPDGate
+.. autoclass:: WeightType
+
+.. autofunction:: generate_qpd_weights
+.. autofunction:: decompose_qpd_instructions
+.. autofunction:: qpdbasis_from_instruction

docs/apidocs/qiskit_addon_cutting.rst

@@ -0,0 +1,28 @@
+=============================================
+Circuit cutting (:mod:`qiskit_addon_cutting`)
+=============================================
+
+.. automodule:: qiskit_addon_cutting
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
+
+.. currentmodule:: qiskit_addon_cutting
+
+.. autofunction:: cut_wires
+.. autofunction:: expand_observables
+.. autofunction:: partition_circuit_qubits
+.. autofunction:: partition_problem
+.. autofunction:: cut_gates
+.. autofunction:: generate_cutting_experiments
+.. autofunction:: reconstruct_expectation_values
+
+.. autoclass:: PartitionedCuttingProblem
+
+Automatic Cut Finding
+~~~~~~~~~~~~~~~~~~~~~
+
+.. autofunction:: find_cuts
+
+.. autoclass:: OptimizationParameters
+.. autoclass:: DeviceConstraints

docs/apidocs/qiskit_addon_cutting.utils.bitwise.rst

@@ -0,0 +1,12 @@
+=============================================================
+Bitwise utilities (:mod:`qiskit_addon_cutting.utils.bitwise`)
+=============================================================
+
+.. automodule:: qiskit_addon_cutting.utils.bitwise
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
+
+.. currentmodule:: qiskit_addon_cutting.utils.bitwise
+
+.. autofunction:: bit_count

docs/apidocs/qiskit_addon_cutting.utils.iteration.rst

@@ -0,0 +1,13 @@
+=================================================================
+Iteration utilities (:mod:`qiskit_addon_cutting.utils.iteration`)
+=================================================================
+
+.. automodule:: qiskit_addon_cutting.utils.iteration
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
+
+.. currentmodule:: qiskit_addon_cutting.utils.iteration
+
+.. autofunction:: unique_by_id
+.. autofunction:: unique_by_eq

docs/apidocs/qiskit_addon_cutting.utils.observable_grouping.rst

@@ -0,0 +1,14 @@
+===========================================================================
+Observable grouping (:mod:`qiskit_addon_cutting.utils.observable_grouping`)
+===========================================================================
+
+.. automodule:: qiskit_addon_cutting.utils.observable_grouping
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
+
+.. currentmodule:: qiskit_addon_cutting.utils.observable_grouping
+
+.. autofunction:: observables_restricted_to_subsystem
+.. autoclass:: CommutingObservableGroup
+.. autoclass:: ObservableCollection

docs/apidocs/qiskit_addon_cutting.utils.simulation.rst

@@ -0,0 +1,13 @@
+===================================================================
+Simulation utilities (:mod:`qiskit_addon_cutting.utils.simulation`)
+===================================================================
+
+.. automodule:: qiskit_addon_cutting.utils.simulation
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
+
+.. currentmodule:: qiskit_addon_cutting.utils.simulation
+
+.. autofunction:: simulate_statevector_outcomes
+.. autoclass:: ExactSampler

docs/apidocs/qiskit_addon_cutting.utils.transforms.rst

@@ -0,0 +1,13 @@
+=========================================================
+Transforms (:mod:`qiskit_addon_cutting.utils.transforms`)
+=========================================================
+
+.. automodule:: qiskit_addon_cutting.utils.transforms
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
+
+.. currentmodule:: qiskit_addon_cutting.utils.transforms
+
+.. autofunction:: separate_circuit
+.. autoclass:: SeparatedCircuits

docs/apidocs/qiskit_addon_cutting.utils.transpiler_passes.rst

@@ -0,0 +1,13 @@
+=======================================================================
+Transpiler passes (:mod:`qiskit_addon_cutting.utils.transpiler_passes`)
+=======================================================================
+
+.. automodule:: qiskit_addon_cutting.utils.transpiler_passes
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
+
+.. currentmodule:: qiskit_addon_cutting.utils.transpiler_passes
+
+.. autoclass:: RemoveFinalReset
+.. autoclass:: ConsolidateResets

docs/conf.py

@@ -103,9 +103,6 @@
 plot_html_show_formats = False
 plot_formats = ["svg"]
 
-# Redirects for pages that have moved
-redirects = {}
-
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
@@ -119,6 +116,54 @@
     "rustworkx": ("https://www.rustworkx.org/", None),
 }
 
+# ----------------------------------------------------------------------------------
+# Redirects
+# ----------------------------------------------------------------------------------
+
+_inlined_apis = [
+    ("qiskit_addon_cutting", "cut_wires"),
+    ("qiskit_addon_cutting", "expand_observables"),
+    ("qiskit_addon_cutting", "partition_circuit_qubits"),
+    ("qiskit_addon_cutting", "partition_problem"),
+    ("qiskit_addon_cutting", "cut_gates"),
+    ("qiskit_addon_cutting", "generate_cutting_experiments"),
+    ("qiskit_addon_cutting", "reconstruct_expectation_values"),
+    ("qiskit_addon_cutting", "PartitionedCuttingProblem"),
+    ("qiskit_addon_cutting", "find_cuts"),
+    ("qiskit_addon_cutting", "OptimizationParameters"),
+    ("qiskit_addon_cutting", "DeviceConstraints"),
+    ("qiskit_addon_cutting.instructions", "CutWire"),
+    ("qiskit_addon_cutting.instructions", "Move"),
+    ("qiskit_addon_cutting.qpd", "QPDBasis"),
+    ("qiskit_addon_cutting.qpd", "BaseQPDGate"),
+    ("qiskit_addon_cutting.qpd", "SingleQubitQPDGate"),
+    ("qiskit_addon_cutting.qpd", "TwoQubitQPDGate"),
+    ("qiskit_addon_cutting.qpd", "WeightType"),
+    ("qiskit_addon_cutting.qpd", "generate_qpd_weights"),
+    ("qiskit_addon_cutting.qpd", "decompose_qpd_instructions"),
+    ("qiskit_addon_cutting.qpd", "qpdbasis_from_instruction"),
+    ("qiskit_addon_cutting.utils.bitwise", "bit_count"),
+    ("qiskit_addon_cutting.utils.iteration", "unique_by_id"),
+    ("qiskit_addon_cutting.utils.iteration", "unique_by_eq"),
+    (
+        "qiskit_addon_cutting.utils.observable_grouping",
+        "observables_restricted_to_subsystem",
+    ),
+    ("qiskit_addon_cutting.utils.observable_grouping", "CommutingObservableGroup"),
+    ("qiskit_addon_cutting.utils.observable_grouping", "ObservableCollection"),
+    ("qiskit_addon_cutting.utils.simulation", "simulate_statevector_outcomes"),
+    ("qiskit_addon_cutting.utils.simulation", "ExactSampler"),
+    ("qiskit_addon_cutting.utils.transforms", "separate_circuit"),
+    ("qiskit_addon_cutting.utils.transforms", "SeparatedCircuits"),
+    ("qiskit_addon_cutting.utils.transpiler_passes", "RemoveFinalReset"),
+    ("qiskit_addon_cutting.utils.transpiler_passes", "ConsolidateResets"),
+]
+
+redirects = {
+    f"stubs/{module}.{name}": f"../apidocs/{module}.html#{module}.{name}"
+    for module, name in _inlined_apis
+}
+
 # ----------------------------------------------------------------------------------
 # Source code links
 # ----------------------------------------------------------------------------------

qiskit_addon_cutting/__init__.py

@@ -9,73 +9,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Circuit Cutting (:mod:`qiskit_addon_cutting`).
-
-.. currentmodule:: qiskit_addon_cutting
-
-Circuit Cutting
-===============
-
-.. autosummary::
-    :toctree: ../stubs/
-    :nosignatures:
-
-    cut_wires
-    expand_observables
-    partition_circuit_qubits
-    partition_problem
-    cut_gates
-    generate_cutting_experiments
-    reconstruct_expectation_values
-
-.. autosummary::
-    :toctree: ../stubs/
-    :nosignatures:
-    :template: autosummary/class_no_inherited_members.rst
-
-    PartitionedCuttingProblem
-    instructions.CutWire
-    instructions.Move
-
-Automatic Cut Finding
-~~~~~~~~~~~~~~~~~~~~~
-
-.. autosummary::
-    :toctree: ../stubs/
-    :nosignatures:
-
-    find_cuts
-
-.. autosummary::
-    :toctree: ../stubs/
-    :nosignatures:
-    :template: autosummary/class_no_inherited_members.rst
-
-    OptimizationParameters
-    DeviceConstraints
-
-Quasi-Probability Decomposition (QPD)
-=====================================
-
-.. autosummary::
-    :toctree: ../stubs/
-    :nosignatures:
-    :template: autosummary/class_no_inherited_members.rst
-
-    qpd.QPDBasis
-    qpd.BaseQPDGate
-    qpd.SingleQubitQPDGate
-    qpd.TwoQubitQPDGate
-    qpd.WeightType
-
-.. autosummary::
-    :toctree: ../stubs/
-    :nosignatures:
-
-    qpd.generate_qpd_weights
-    qpd.decompose_qpd_instructions
-    qpd.qpdbasis_from_instruction
-"""
+"""Circuit cutting."""
 
 from __future__ import annotations
 from importlib.metadata import version, PackageNotFoundError

qiskit_addon_cutting/cut_finding/__init__.py

@@ -7,4 +7,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
+# Warning: this module is not documented and it does not have an RST file.
+# If we ever publicly expose interfaces users can import from this module,
+# we should set up its RST file.
 """Main automated cut finding functionality."""

qiskit_addon_cutting/instructions/__init__.py

@@ -9,6 +9,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
+# Reminder: update the RST file in docs/apidocs when adding new interfaces.
 r"""Quantum circuit :class:`~qiskit.Instruction`\ s useful for circuit cutting."""
 
 from .cut_wire import CutWire

qiskit_addon_cutting/qpd/__init__.py

@@ -9,6 +9,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
+# Reminder: update the RST file in docs/apidocs when adding new interfaces.
 """Main quasiprobability decomposition functionality."""
 
 from .qpd_basis import QPDBasis

qiskit_addon_cutting/qpd/instructions/__init__.py

@@ -9,6 +9,8 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
+# Warning: this module is not documented and it does not have an RST file
+# because its members are already documented in the parent module.
 r"""Quantum circuit :class:`~qiskit.Instruction`\ s for representing quasiprobability decompositions."""
 
 from .qpd_gate import BaseQPDGate, SingleQubitQPDGate, TwoQubitQPDGate