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. (cherry picked from commit 0667163)
Qiskit · Oct 30, 2024 · 6a22190 · 6a22190
1 parent 5be2258
commit 6a22190
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