Reorganize API docs (#88) (#90)

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

Some notes:

* Removes `qiskit_addon_sqd.rst`, since users don't actually import this module directly 
* Inlines every function<hr>This is an automatic backport of pull request #88 done by [Mergify](https://mergify.com).

docs/apidocs/index.rst

@@ -0,0 +1,12 @@
+**********************************
+``qiskit-addon-sqd`` API reference
+**********************************
+
+.. toctree::
+   :maxdepth: 1
+
+   qiskit_addon_sqd.configuration_recovery
+   qiskit_addon_sqd.counts
+   qiskit_addon_sqd.fermion
+   qiskit_addon_sqd.qubit
+   qiskit_addon_sqd.subsampling

docs/apidocs/qiskit_addon_sqd.configuration_recovery.rst

@@ -1,10 +1,13 @@
-======================
-Configuration Recovery
-======================
-
-.. _qiskit_addon_sqd-configuration_recovery:
+=======================================================================
+Configuration recovery (:mod:`qiskit_addon_sqd.configuration_recovery`)
+=======================================================================
 
 .. automodule:: qiskit_addon_sqd.configuration_recovery
    :no-members:
    :no-inherited-members:
    :no-special-members:
+
+.. currentmodule:: qiskit_addon_sqd.configuration_recovery
+
+.. autofunction:: post_select_by_hamming_weight
+.. autofunction:: recover_configurations

docs/apidocs/qiskit_addon_sqd.counts.rst

@@ -1,10 +1,15 @@
-======
-Counts
-======
-
-.. _qiskit_addon_sqd-counts:
+=======================================
+Counts (:mod:`qiskit_addon_sqd.counts`)
+=======================================
 
 .. automodule:: qiskit_addon_sqd.counts
    :no-members:
    :no-inherited-members:
    :no-special-members:
+
+.. currentmodule:: qiskit_addon_sqd.counts
+
+.. autofunction:: counts_to_arrays
+.. autofunction:: generate_counts_uniform
+.. autofunction:: generate_counts_bipartite_hamming
+.. autofunction:: normalize_counts_dict

docs/apidocs/qiskit_addon_sqd.fermion.rst

@@ -1,10 +1,18 @@
-=======
-Fermion
-=======
-
-.. _qiskit_addon_sqd-fermion:
+=========================================
+Fermion (:mod:`qiskit_addon_sqd.fermion`)
+=========================================
 
 .. automodule:: qiskit_addon_sqd.fermion
    :no-members:
    :no-inherited-members:
    :no-special-members:
+
+.. currentmodule:: qiskit_addon_sqd.fermion
+
+.. autofunction:: bitstring_matrix_to_ci_strs
+.. autofunction:: enlarge_batch_from_transitions
+.. autofunction:: flip_orbital_occupancies
+.. autofunction:: solve_fermion
+.. autofunction:: optimize_orbitals
+.. autofunction:: rotate_integrals
+.. autofunction:: bitstring_matrix_to_sorted_addresses

docs/apidocs/qiskit_addon_sqd.qubit.rst

@@ -1,10 +1,15 @@
-=====
-Qubit
-=====
-
-.. _qiskit_addon_sqd-qubit:
+=====================================
+Qubit (:mod:`qiskit_addon_sqd.qubit`)
+=====================================
 
 .. automodule:: qiskit_addon_sqd.qubit
    :no-members:
    :no-inherited-members:
    :no-special-members:
+
+.. currentmodule:: qiskit_addon_sqd.qubit
+
+.. autofunction:: solve_qubit
+.. autofunction:: project_operator_to_subspace
+.. autofunction:: sort_and_remove_duplicates
+.. autofunction:: matrix_elements_from_pauli

docs/apidocs/qiskit_addon_sqd.subsampling.rst

@@ -1,10 +1,13 @@
-===========
-Subsampling
-===========
-
-.. _qiskit_addon_sqd-subsampling:
+=================================================
+Subsampling (:mod:`qiskit_addon_sqd.subsampling`)
+=================================================
 
 .. automodule:: qiskit_addon_sqd.subsampling
    :no-members:
    :no-inherited-members:
    :no-special-members:
+
+.. currentmodule:: qiskit_addon_sqd.subsampling
+
+.. autofunction:: subsample
+.. autofunction:: postselect_and_subsample

docs/conf.py

@@ -59,6 +59,7 @@
     "sphinx.ext.intersphinx",
     "matplotlib.sphinxext.plot_directive",
     "sphinx_copybutton",
+    "sphinx_reredirects",
     "reno.sphinxext",
     "nbsphinx",
     "qiskit_sphinx_theme",
@@ -107,6 +108,41 @@
 plot_working_directory = "."
 plot_html_show_source_link = False
 
+# ----------------------------------------------------------------------------------
+# Redirects
+# ----------------------------------------------------------------------------------
+
+_inlined_apis = [
+    ("qiskit_addon_sqd.configuration_recovery", "post_select_by_hamming_weight"),
+    ("qiskit_addon_sqd.configuration_recovery", "recover_configurations"),
+    ("qiskit_addon_sqd.counts", "counts_to_arrays"),
+    ("qiskit_addon_sqd.counts", "generate_counts_uniform"),
+    ("qiskit_addon_sqd.counts", "generate_counts_bipartite_hamming"),
+    ("qiskit_addon_sqd.counts", "normalize_counts_dict"),
+    ("qiskit_addon_sqd.fermion", "bitstring_matrix_to_ci_strs"),
+    ("qiskit_addon_sqd.fermion", "enlarge_batch_from_transitions"),
+    ("qiskit_addon_sqd.fermion", "flip_orbital_occupancies"),
+    ("qiskit_addon_sqd.fermion", "solve_fermion"),
+    ("qiskit_addon_sqd.fermion", "optimize_orbitals"),
+    ("qiskit_addon_sqd.fermion", "rotate_integrals"),
+    ("qiskit_addon_sqd.fermion", "bitstring_matrix_to_sorted_addresses"),
+    ("qiskit_addon_sqd.qubit", "solve_qubit"),
+    ("qiskit_addon_sqd.qubit", "project_operator_to_subspace"),
+    ("qiskit_addon_sqd.qubit", "project_operator_to_subspace"),
+    ("qiskit_addon_sqd.qubit", "sort_and_remove_duplicates"),
+    ("qiskit_addon_sqd.qubit", "matrix_elements_from_pauli"),
+    ("qiskit_addon_sqd.subsampling", "subsample"),
+    ("qiskit_addon_sqd.subsampling", "postselect_and_subsample"),
+]
+
+redirects = {
+    "apidocs/qiskit_addon_sqd": "./index.html",
+    **{
+        f"stubs/{module}.{name}": f"../apidocs/{module}.html#{module}.{name}"
+        for module, name in _inlined_apis
+    },
+}
+
 # ----------------------------------------------------------------------------------
 # Source code links
 # ----------------------------------------------------------------------------------

docs/index.rst

@@ -97,6 +97,6 @@ References
    Installation Instructions <install>
    Tutorials <tutorials/index>
    How-To Guides <how_tos/index>
-   API Reference <apidocs/qiskit_addon_sqd>
+   API Reference <apidocs/index>
    GitHub <https://github.com/qiskit/qiskit-addon-sqd>
    Release Notes <release-notes>

pyproject.toml

@@ -74,6 +74,7 @@ docs = [
     "sphinx-design",
     "sphinx-autodoc-typehints",
     "sphinx-copybutton",
+    "sphinx_reredirects",
     "nbsphinx>=0.9.4",
     "reno>=4.1",
 ]

qiskit_addon_sqd/__init__.py

@@ -10,22 +10,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Primary SQD functionality.
-
-.. currentmodule:: qiskit_addon_sqd
-
-.. autosummary::
-   :toctree: ../stubs/
-   :nosignatures:
-
-Modules
-=======
-.. autosummary::
-   :toctree:
-
-   configuration_recovery
-   subsampling
-   counts
-   fermion
-   qubit
-"""
+# 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.
+"""Primary SQD functionality."""

qiskit_addon_sqd/configuration_recovery.py

@@ -10,17 +10,8 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Functions for performing self-consistent configuration recovery.
-
-.. currentmodule:: qiskit_addon_sqd.configuration_recovery
-
-.. autosummary::
-   :toctree: ../stubs/
-   :nosignatures:
-
-   post_select_by_hamming_weight
-   recover_configurations
-"""
+# Reminder: update the RST file in docs/apidocs when adding new interfaces.
+"""Functions for performing self-consistent configuration recovery."""
 
 from __future__ import annotations
 

qiskit_addon_sqd/counts.py

@@ -10,19 +10,8 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Functions for transforming counts dictionaries.
-
-.. currentmodule:: qiskit_addon_sqd.counts
-
-.. autosummary::
-   :toctree: ../stubs/
-   :nosignatures:
-
-   counts_to_arrays
-   generate_counts_uniform
-   generate_counts_bipartite_hamming
-   normalize_counts_dict
-"""
+# Reminder: update the RST file in docs/apidocs when adding new interfaces.
+"""Functions for transforming counts dictionaries."""
 
 from __future__ import annotations
 

qiskit_addon_sqd/fermion.py

@@ -10,22 +10,8 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Functions for the study of fermionic systems.
-
-.. currentmodule:: qiskit_addon_sqd.fermion
-
-.. autosummary::
-   :toctree: ../stubs/
-   :nosignatures:
-
-   bitstring_matrix_to_ci_strs
-   enlarge_batch_from_transitions
-   flip_orbital_occupancies
-   solve_fermion
-   optimize_orbitals
-   rotate_integrals
-   bitstring_matrix_to_sorted_addresses
-"""
+# Reminder: update the RST file in docs/apidocs when adding new interfaces.
+"""Functions for the study of fermionic systems."""
 
 from __future__ import annotations
 

qiskit_addon_sqd/qubit.py

@@ -10,20 +10,8 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Functions for handling quantum samples.
-
-.. currentmodule:: qiskit_addon_sqd.qubit
-
-.. autosummary::
-   :toctree: ../stubs/
-   :nosignatures:
-
-   solve_qubit
-   project_operator_to_subspace
-   sort_and_remove_duplicates
-   matrix_elements_from_pauli
-   sort_and_remove_duplicates
-"""
+# Reminder: update the RST file in docs/apidocs when adding new interfaces.
+"""Functions for handling quantum samples."""
 
 from typing import Any
 

qiskit_addon_sqd/subsampling.py

@@ -10,17 +10,8 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Functions for creating batches of samples from a bitstring matrix.
-
-.. currentmodule:: qiskit_addon_sqd.subsampling
-
-.. autosummary::
-   :toctree: ../stubs/
-   :nosignatures:
-
-   subsample
-   postselect_and_subsample
-"""
+# Reminder: update the RST file in docs/apidocs when adding new interfaces.
+"""Functions for creating batches of samples from a bitstring matrix."""
 
 from __future__ import annotations