Reorganize API docs (#22)

Applies the same changes from Qiskit/qiskit-addon-obp#24. Refer to that for more explanation. Some notes: * Removes `qiskit_addon_mpf.rst`, since users don't actually import this module directly * Inlines the three functions and one class in `qiskit_addon_mpf.static`. This means that it is our only API file, since there is only one module! - I'm not 100% sure it makes sense to inline these interfaces. Feel free to push back. They all seemed small enough to be worth it, but you can disagree.
Qiskit · Oct 30, 2024 · 0667163 · 0667163
1 parent d70fb57
commit 0667163
Show file tree

Hide file tree

Showing 8 changed files with 57 additions and 65 deletions.
diff --git a/docs/apidocs/index.rst b/docs/apidocs/index.rst
@@ -0,0 +1,8 @@
+**********************************
+``qiskit-addon-mpf`` API reference
+**********************************
+
+.. toctree::
+   :maxdepth: 1
+
+   qiskit_addon_mpf.static
diff --git a/docs/apidocs/qiskit_addon_mpf.rst b/docs/apidocs/qiskit_addon_mpf.rst
diff --git a/docs/apidocs/qiskit_addon_mpf.static.rst b/docs/apidocs/qiskit_addon_mpf.static.rst
@@ -1,10 +1,26 @@
-===========
-Static MPFs
-===========
-
-.. _qiskit_addon_mpf-static:
+============================================
+Static MPFs (:mod:`qiskit_addon_mpf.static`)
+============================================
 
 .. automodule:: qiskit_addon_mpf.static
    :no-members:
    :no-inherited-members:
    :no-special-members:
+
+.. currentmodule:: qiskit_addon_mpf.static
+
+Linear system of equations utilities
+------------------------------------
+
+.. autoclass:: LSE   
+.. autofunction:: setup_lse
+
+Exact static MPF coefficients
+-----------------------------
+
+.. autofunction:: setup_exact_model
+
+Approximate static MPF coefficients
+-----------------------------------
+
+.. autofunction:: setup_approximate_model
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",
@@ -110,6 +111,25 @@
 plot_working_directory = "."
 plot_html_show_source_link = False
 
+# ----------------------------------------------------------------------------------
+# Redirects
+# ----------------------------------------------------------------------------------
+
+_inlined_apis = [
+    ("qiskit_addon_mpf.static", "LSE"),
+    ("qiskit_addon_mpf.static", "setup_lse"),
+    ("qiskit_addon_mpf.static", "setup_exact_model"),
+    ("qiskit_addon_mpf.static", "setup_approximate_model"),
+]
+
+redirects = {
+    "apidocs/qiskit_addon_mpf": "./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
@@ -70,6 +70,6 @@ License
    Tutorials <tutorials/index>
    How-To Guides <how_tos/index>
    Explanations <explanations/index>
-   API Reference <apidocs/qiskit_addon_mpf>
+   API Reference <apidocs/index>
    GitHub <https://github.com/Qiskit/qiskit-addon-mpf>
    Release Notes <release-notes>
diff --git a/pyproject.toml b/pyproject.toml
@@ -79,6 +79,7 @@ docs = [
     "sphinx-design",
     "sphinx-autodoc-typehints",
     "sphinx-copybutton",
+    "sphinx_reredirects",
     "nbsphinx>=0.9.4",
     "reno>=4.1",
 ]

diff --git a/qiskit_addon_mpf/__init__.py b/qiskit_addon_mpf/__init__.py
@@ -10,20 +10,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Multi-product formulas.
-
-.. currentmodule:: qiskit_addon_mpf
-
-.. autosummary::
-   :toctree:  ../stubs/
-   :nosignatures:
-
-Submodules
-==========
-
-.. autosummary::
-   :toctree:
-
-   static
-
-"""
+# 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.
+"""Multi-product formulas."""
diff --git a/qiskit_addon_mpf/static/__init__.py b/qiskit_addon_mpf/static/__init__.py
@@ -10,38 +10,8 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Static MPFs.
-
-.. currentmodule:: qiskit_addon_mpf.static
-
-Linear system of equations utilities
-------------------------------------
-
-.. autosummary::
-   :toctree:  ../stubs/
-   :nosignatures:
-
-   LSE
-   setup_lse
-
-Exact static MPF coefficients
------------------------------
-
-.. autosummary::
-   :toctree:  ../stubs/
-   :nosignatures:
-
-   setup_exact_model
-
-Approximate static MPF coefficients
------------------------------------
-
-.. autosummary::
-   :toctree:  ../stubs/
-   :nosignatures:
-
-   setup_approximate_model
-"""
+# Reminder: update the RST file in docs/apidocs when adding new interfaces.
+"""Static MPFs."""
 
 from .approximate import setup_approximate_model
 from .exact import setup_exact_model