Reorganize API docs (backport #24) (#29)

## Changes ### Adds index page This page is important so that `docs.quantum.ibm.com/api/qiskit-addon-obp` does not 404. It should simply be a flat list of every documented module. ### Flattens submodules We've gotten prior user complaints that they don't like when docs have a lot of nesting. So, docs.quantum.ibm.com expects all modules to be flattened to the same level in the left ToC. This means that users access submodules via the left ToC, rather than through the parent module's page. Due to this change, we delete qiskit_addon_obp.utils because it does not actually have any importable interfaces. If the module list ever gets too big, the qiskit/documentation repository has a mechanism to let you group modules into parent folders (see https://docs.quantum.ibm.com/api/qiskit). ### Sets module metadata & moves structural directives to RST The script in `qiskit/documentation` expects you to set ``(:mod:`qiskit_addon_obp`)`` at the top of every module page. We need this to extract metadata, which we use to set up the left ToC and `<head>` metadata for the page. We also now set all the `.. autodoc` directives like `.. autosummary` in RST. Sphinx [doesn't mix well](https://stackoverflow.com/questions/62855567/headings-when-using-autodoc-in-sphinx) when you have some structural elements like headings in RST and some in Python, so it's important to be consistent with where those structural elements go. Putting it in RST is more conventional, and it avoids us having to disable three Ruff lint rules. For modules, most the docs should be in the RST file other than a one-sentence summary of the module. ### Inlines functions and some classes We've gotten prior user complaints that they don't like when you have to click to a bunch of subpages to see individual functions and classes. So, we've generally adopted the approach of inlining functions and smaller classes. Larger classes and functions can still live on dedicated pages. The right page ToC makes it so that users can still jump around the page. This change is subjective. Feel free to push back if you think any particular interface should be a dedicated page! We set up client-redirects using sphinx-reredirects to avoid 404s. We used this extension well with Qiskit SDK. ## Results <details><summary>docs.quantum.ibm.com</summary> <img width="976" alt="Screenshot 2024-10-22 at 3 22 32 PM" src="https://github.com/user-attachments/assets/33bc2458-397f-4541-a7ba-2655b32c8c80"> </details> <details><summary>GitHub Pages</summary> <img width="289" alt="Screenshot 2024-10-22 at 3 31 20 PM" src="https://github.com/user-attachments/assets/70bd5d2a-fd05-4fd8-ad0d-efed379688bf"> <img width="625" alt="Screenshot 2024-10-22 at 3 31 23 PM" src="https://github.com/user-attachments/assets/9de98b41-d0b0-44b9-bcce-dbb1844b1057"> </details> <hr>This is an automatic backport of pull request #24 done by [Mergify](https://mergify.com).
Qiskit · Oct 28, 2024 · 472badc · 472badc
1 parent 26108db
commit 472badc
Show file tree

Hide file tree

Showing 18 changed files with 124 additions and 134 deletions.
diff --git a/docs/apidocs/index.rst b/docs/apidocs/index.rst
@@ -0,0 +1,13 @@
+**********************************
+``qiskit-addon-obp`` API reference
+**********************************
+
+.. toctree::
+   :maxdepth: 1
+
+   qiskit_addon_obp
+   qiskit_addon_obp.utils.metadata
+   qiskit_addon_obp.utils.operations
+   qiskit_addon_obp.utils.simplify
+   qiskit_addon_obp.utils.truncating
+   qiskit_addon_obp.utils.visualization
diff --git a/docs/apidocs/qiskit_addon_obp.rst b/docs/apidocs/qiskit_addon_obp.rst
@@ -1,10 +1,12 @@
-============================================
-Qiskit addon: operator backpropagation (OBP)
-============================================
-
-.. _qiskit_addon_obp:
+==================================================
+Operator backpropagation (:mod:`qiskit_addon_obp`)
+==================================================
 
 .. automodule:: qiskit_addon_obp
    :no-members:
    :no-inherited-members:
    :no-special-members:
+
+.. currentmodule:: qiskit_addon_obp
+
+.. autofunction:: backpropagate
diff --git a/docs/apidocs/qiskit_addon_obp.utils.metadata.rst b/docs/apidocs/qiskit_addon_obp.utils.metadata.rst
@@ -1,10 +1,17 @@
-========
-metadata
-========
-
-.. _qiskit_addon_obp-utils-metadata:
+===========================================================
+Metadata utilities (:mod:`qiskit_addon_obp.utils.metadata`)
+===========================================================
 
 .. automodule:: qiskit_addon_obp.utils.metadata
    :no-members:
    :no-inherited-members:
    :no-special-members:
+
+.. currentmodule:: qiskit_addon_obp.utils.metadata
+
+.. autosummary::
+   :toctree: ../stubs/
+   :nosignatures:
+
+   OBPMetadata
+   SliceMetadata
diff --git a/docs/apidocs/qiskit_addon_obp.utils.operations.rst b/docs/apidocs/qiskit_addon_obp.utils.operations.rst
@@ -1,10 +1,15 @@
-==========
-operations
-==========
-
-.. _qiskit_addon_obp-utils-operations:
+=============================================================
+Operator utilities (:mod:`qiskit_addon_obp.utils.operations`)
+=============================================================
 
 .. automodule:: qiskit_addon_obp.utils.operations
    :no-members:
    :no-inherited-members:
    :no-special-members:
+
+.. currentmodule:: qiskit_addon_obp.utils.operations
+
+.. autofunction:: apply_op_to
+.. autofunction:: apply_reset_to
+.. autofunction:: to_global_op
+.. autofunction:: reduce_op
diff --git a/docs/apidocs/qiskit_addon_obp.utils.rst b/docs/apidocs/qiskit_addon_obp.utils.rst
diff --git a/docs/apidocs/qiskit_addon_obp.utils.simplify.rst b/docs/apidocs/qiskit_addon_obp.utils.simplify.rst
@@ -1,10 +1,14 @@
-========
-simplify
-========
-
-.. _qiskit_addon_obp-utils-simplify:
+======================================================================
+Pauli operator simplification (:mod:`qiskit_addon_obp.utils.simplify`)
+======================================================================
 
 .. automodule:: qiskit_addon_obp.utils.simplify
    :no-members:
    :no-inherited-members:
    :no-special-members:
+
+.. currentmodule:: qiskit_addon_obp.utils.simplify
+
+.. autoclass:: OperatorBudget
+.. autoclass:: SimplifyMetadata
+.. autofunction:: simplify
diff --git a/docs/apidocs/qiskit_addon_obp.utils.truncating.rst b/docs/apidocs/qiskit_addon_obp.utils.truncating.rst
@@ -1,10 +1,14 @@
-==========
-truncating
-==========
-
-.. _qiskit_addon_obp-utils-truncating:
+===============================================================
+Truncation utilities (:mod:`qiskit_addon_obp.utils.truncating`)
+===============================================================
 
 .. automodule:: qiskit_addon_obp.utils.truncating
    :no-members:
    :no-inherited-members:
    :no-special-members:
+
+.. currentmodule:: qiskit_addon_obp.utils.truncating
+
+.. autoclass:: TruncationErrorBudget
+.. autofunction:: setup_budget
+.. autofunction:: truncate_binary_search
diff --git a/docs/apidocs/qiskit_addon_obp.utils.visualization.rst b/docs/apidocs/qiskit_addon_obp.utils.visualization.rst
@@ -1,10 +1,18 @@
-=============
-visualization
-=============
-
-.. _qiskit_addon_obp-utils-visualization:
+=====================================================================
+Visualization utilities (:mod:`qiskit_addon_obp.utils.visualization`)
+=====================================================================
 
 .. automodule:: qiskit_addon_obp.utils.visualization
    :no-members:
    :no-inherited-members:
    :no-special-members:
+
+.. currentmodule:: qiskit_addon_obp.utils.visualization
+
+.. autofunction:: plot_accumulated_error
+.. autofunction:: plot_left_over_error_budget
+.. autofunction:: plot_slice_errors
+.. autofunction:: plot_num_paulis
+.. autofunction:: plot_num_truncated_paulis
+.. autofunction:: plot_sum_paulis
+.. autofunction:: plot_num_qwc_groups
diff --git a/docs/conf.py b/docs/conf.py
@@ -58,6 +58,7 @@
     "sphinx.ext.intersphinx",
     "matplotlib.sphinxext.plot_directive",
     "sphinx_copybutton",
+    "sphinx_reredirects",
     "reno.sphinxext",
     "nbsphinx",
     "qiskit_sphinx_theme",
@@ -108,6 +109,38 @@
 plot_working_directory = "."
 plot_html_show_source_link = False
 
+# ----------------------------------------------------------------------------------
+# Redirects
+# ----------------------------------------------------------------------------------
+
+_inlined_apis = [
+    ("qiskit_addon_obp", "backpropagate"),
+    ("qiskit_addon_obp.utils.operations", "apply_op_to"),
+    ("qiskit_addon_obp.utils.operations", "to_global_op"),
+    ("qiskit_addon_obp.utils.operations", "reduce_op"),
+    ("qiskit_addon_obp.utils.simplify", "OperatorBudget"),
+    ("qiskit_addon_obp.utils.simplify", "SimplifyMetadata"),
+    ("qiskit_addon_obp.utils.simplify", "simplify"),
+    ("qiskit_addon_obp.utils.truncating", "TruncationErrorBudget"),
+    ("qiskit_addon_obp.utils.truncating", "setup_budget"),
+    ("qiskit_addon_obp.utils.truncating", "truncate_binary_search"),
+    ("qiskit_addon_obp.utils.visualization", "plot_accumulated_error"),
+    ("qiskit_addon_obp.utils.visualization", "plot_left_over_error_budget"),
+    ("qiskit_addon_obp.utils.visualization", "plot_slice_errors"),
+    ("qiskit_addon_obp.utils.visualization", "plot_num_paulis"),
+    ("qiskit_addon_obp.utils.visualization", "plot_num_truncated_paulis"),
+    ("qiskit_addon_obp.utils.visualization", "plot_sum_paulis"),
+    ("qiskit_addon_obp.utils.visualization", "plot_num_qwc_groups"),
+]
+
+redirects = {
+    "apidocs/qiskit_addon_obp.utils": "./index.html",
+    **{
+        f"stubs/{module}.{name}": f"../apidocs/{module}.html#{module}.{name}"
+        for module, name in _inlined_apis
+    },
+}
+
 # ----------------------------------------------------------------------------------
 # Source code links
 # ----------------------------------------------------------------------------------

diff --git a/docs/index.rst b/docs/index.rst
@@ -78,6 +78,6 @@ License
    Installation Instructions <install>
    Tutorials <tutorials/index>
    How-To Guides <how_tos/index>
-   API Reference <apidocs/qiskit_addon_obp>
+   API Reference <apidocs/index>
    GitHub <https://github.com/Qiskit/qiskit-addon-obp>
    Release Notes <release-notes>
diff --git a/pyproject.toml b/pyproject.toml
@@ -77,6 +77,7 @@ docs = [
     "jupyter-sphinx",
     "sphinx-design",
     "sphinx-autodoc-typehints",
+    "sphinx-reredirects",
     "sphinx-copybutton",
     "nbsphinx>=0.9.4",
     "reno>=4.1",

diff --git a/qiskit_addon_obp/__init__.py b/qiskit_addon_obp/__init__.py
@@ -10,24 +10,8 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Main operator backpropagation functionality.
-
-.. currentmodule:: qiskit_addon_obp
-
-.. autosummary::
-   :toctree: ../stubs/
-   :nosignatures:
-
-   backpropagate
-
-Submodules
-==========
-
-.. autosummary::
-   :toctree:
-
-   utils
-"""
+# Reminder: update the RST file in docs/apidocs when adding new interfaces.
+"""Main operator backpropagation functionality."""
 
 from .backpropagation import backpropagate
 

diff --git a/qiskit_addon_obp/utils/__init__.py b/qiskit_addon_obp/utils/__init__.py
@@ -10,16 +10,8 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Utility functionality for conducting operator backpropagation.
 
-.. currentmodule:: qiskit_addon_obp.utils
-
-.. autosummary::
-   :toctree:
-
-   metadata
-   operations
-   simplify
-   truncating
-   visualization
-"""
+# 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.
+"""Utility functionality for conducting operator backpropagation."""
diff --git a/qiskit_addon_obp/utils/metadata.py b/qiskit_addon_obp/utils/metadata.py
@@ -10,17 +10,8 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Container classes for holding backpropagation metadata.
-
-.. currentmodule:: qiskit_addon_obp.utils.metadata
-
-.. autosummary::
-   :toctree: ../stubs/
-   :nosignatures:
-
-   OBPMetadata
-   SliceMetadata
-"""
+# Reminder: update the RST file in docs/apidocs when adding new interfaces.
+"""Container classes for holding backpropagation metadata."""
 
 from __future__ import annotations
 

diff --git a/qiskit_addon_obp/utils/operations.py b/qiskit_addon_obp/utils/operations.py
@@ -10,18 +10,8 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Utility functions for operator backpropagation.
-
-.. currentmodule:: qiskit_addon_obp.utils.operations
-
-.. autosummary::
-   :toctree: ../stubs/
-   :nosignatures:
-
-   apply_op_to
-   to_global_op
-   reduce_op
-"""
+# Reminder: update the RST file in docs/apidocs when adding new interfaces.
+"""Utility functions for operator backpropagation."""
 
 from __future__ import annotations
 

diff --git a/qiskit_addon_obp/utils/simplify.py b/qiskit_addon_obp/utils/simplify.py
@@ -10,18 +10,8 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Functions for simplifying Pauli operators.
-
-.. currentmodule:: qiskit_addon_obp.utils.simplify
-
-.. autosummary::
-   :toctree: ../stubs/
-   :nosignatures:
-
-   OperatorBudget
-   SimplifyMetadata
-   simplify
-"""
+# Reminder: update the RST file in docs/apidocs when adding new interfaces.
+"""Functions for simplifying Pauli operators."""
 
 from __future__ import annotations
 

diff --git a/qiskit_addon_obp/utils/truncating.py b/qiskit_addon_obp/utils/truncating.py
@@ -10,18 +10,8 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Functions for truncating Pauli operators within given error budgets.
-
-.. currentmodule:: qiskit_addon_obp.utils.truncating
-
-.. autosummary::
-   :toctree: ../stubs/
-   :nosignatures:
-
-   TruncationErrorBudget
-   setup_budget
-   truncate_binary_search
-"""
+# Reminder: update the RST file in docs/apidocs when adding new interfaces.
+"""Functions for truncating Pauli operators within given error budgets."""
 
 from __future__ import annotations
 

diff --git a/qiskit_addon_obp/utils/visualization.py b/qiskit_addon_obp/utils/visualization.py
@@ -10,22 +10,8 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Various visualization utilities.
-
-.. currentmodule:: qiskit_addon_obp.utils.visualization
-
-.. autosummary::
-   :toctree: ../stubs/
-   :nosignatures:
-
-   plot_accumulated_error
-   plot_left_over_error_budget
-   plot_slice_errors
-   plot_num_paulis
-   plot_num_truncated_paulis
-   plot_sum_paulis
-   plot_num_qwc_groups
-"""
+# Reminder: update the RST file in docs/apidocs when adding new interfaces.
+"""Various visualization utilities."""
 
 from __future__ import annotations