From 472badc5d4fed0485b5754594f0434a155f52e74 Mon Sep 17 00:00:00 2001 From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com> Date: Mon, 28 Oct 2024 13:14:54 -0400 Subject: [PATCH] Reorganize API docs (backport #24) (#29) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 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 `` 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
docs.quantum.ibm.com Screenshot 2024-10-22 at 3 22 32 PM
GitHub Pages Screenshot 2024-10-22 at 3 31 20 PM Screenshot 2024-10-22 at 3 31 23 PM
This is an automatic backport of pull request #24 done by [Mergify](https://mergify.com). --- docs/apidocs/index.rst | 13 ++++++++ docs/apidocs/qiskit_addon_obp.rst | 12 ++++--- .../qiskit_addon_obp.utils.metadata.rst | 17 +++++++--- .../qiskit_addon_obp.utils.operations.rst | 15 ++++++--- docs/apidocs/qiskit_addon_obp.utils.rst | 10 ------ .../qiskit_addon_obp.utils.simplify.rst | 14 +++++--- .../qiskit_addon_obp.utils.truncating.rst | 14 +++++--- .../qiskit_addon_obp.utils.visualization.rst | 18 +++++++--- docs/conf.py | 33 +++++++++++++++++++ docs/index.rst | 2 +- pyproject.toml | 1 + qiskit_addon_obp/__init__.py | 20 ++--------- qiskit_addon_obp/utils/__init__.py | 16 +++------ qiskit_addon_obp/utils/metadata.py | 13 ++------ qiskit_addon_obp/utils/operations.py | 14 ++------ qiskit_addon_obp/utils/simplify.py | 14 ++------ qiskit_addon_obp/utils/truncating.py | 14 ++------ qiskit_addon_obp/utils/visualization.py | 18 ++-------- 18 files changed, 124 insertions(+), 134 deletions(-) create mode 100644 docs/apidocs/index.rst delete mode 100644 docs/apidocs/qiskit_addon_obp.utils.rst diff --git a/docs/apidocs/index.rst b/docs/apidocs/index.rst new file mode 100644 index 0000000..eb6d795 --- /dev/null +++ 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 index e4719a8..7128b38 100644 --- 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 index 6e0d35e..919d65f 100644 --- 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 index 77b4bc2..60e4831 100644 --- 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 deleted file mode 100644 index cdb207c..0000000 --- a/docs/apidocs/qiskit_addon_obp.utils.rst +++ /dev/null @@ -1,10 +0,0 @@ -===== -utils -===== - -.. _qiskit_addon_obp-utils: - -.. automodule:: qiskit_addon_obp.utils - :no-members: - :no-inherited-members: - :no-special-members: diff --git a/docs/apidocs/qiskit_addon_obp.utils.simplify.rst b/docs/apidocs/qiskit_addon_obp.utils.simplify.rst index d7e70df..7fb6038 100644 --- 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 index ea3f5a2..e36b08f 100644 --- 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 index b408821..e9e2d47 100644 --- 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 index 0f665a9..f49c5eb 100644 --- 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 index f6b2b54..6d25534 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -78,6 +78,6 @@ License Installation Instructions Tutorials How-To Guides - API Reference + API Reference GitHub Release Notes diff --git a/pyproject.toml b/pyproject.toml index db48c3e..e35b52e 100644 --- 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 index 342ae3d..34bc532 100644 --- 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 index 13c8dc9..8b27d6b 100644 --- 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 index f5eb4a0..08ff8ee 100644 --- 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 index 770daf4..f155be6 100644 --- 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 index bfb96de..b7e6e41 100644 --- 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 index 282ec5c..84bd27d 100644 --- 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 index a148a70..1336b9b 100644 --- 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