diff --git a/docs/apidocs/index.rst b/docs/apidocs/index.rst new file mode 100644 index 0000000..a0a6cfd --- /dev/null +++ b/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 diff --git a/docs/apidocs/qiskit_addon_sqd.configuration_recovery.rst b/docs/apidocs/qiskit_addon_sqd.configuration_recovery.rst index 7724266..0b1ecee 100644 --- a/docs/apidocs/qiskit_addon_sqd.configuration_recovery.rst +++ b/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 diff --git a/docs/apidocs/qiskit_addon_sqd.counts.rst b/docs/apidocs/qiskit_addon_sqd.counts.rst index 9d80a54..c47a4b9 100644 --- a/docs/apidocs/qiskit_addon_sqd.counts.rst +++ b/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 diff --git a/docs/apidocs/qiskit_addon_sqd.fermion.rst b/docs/apidocs/qiskit_addon_sqd.fermion.rst index 2470c78..27c7c9e 100644 --- a/docs/apidocs/qiskit_addon_sqd.fermion.rst +++ b/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 diff --git a/docs/apidocs/qiskit_addon_sqd.qubit.rst b/docs/apidocs/qiskit_addon_sqd.qubit.rst index 7eec7fa..dfd09ef 100644 --- a/docs/apidocs/qiskit_addon_sqd.qubit.rst +++ b/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 diff --git a/docs/apidocs/qiskit_addon_sqd.rst b/docs/apidocs/qiskit_addon_sqd.rst deleted file mode 100644 index 94e67a0..0000000 --- a/docs/apidocs/qiskit_addon_sqd.rst +++ /dev/null @@ -1,10 +0,0 @@ -==================================== -Sample-based Quantum Diagonalization -==================================== - -.. _qiskit_addon_sqd: - -.. automodule:: qiskit_addon_sqd - :no-members: - :no-inherited-members: - :no-special-members: diff --git a/docs/apidocs/qiskit_addon_sqd.subsampling.rst b/docs/apidocs/qiskit_addon_sqd.subsampling.rst index f043d8a..da7708e 100644 --- a/docs/apidocs/qiskit_addon_sqd.subsampling.rst +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index 90ec773..0854e3f 100644 --- a/docs/conf.py +++ b/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 # ---------------------------------------------------------------------------------- diff --git a/docs/index.rst b/docs/index.rst index 805d76e..d4dc338 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -97,6 +97,6 @@ References Installation Instructions Tutorials How-To Guides - API Reference + API Reference GitHub Release Notes diff --git a/pyproject.toml b/pyproject.toml index 7c7eaa3..9651efb 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -75,6 +75,7 @@ docs = [ "sphinx-design", "sphinx-autodoc-typehints", "sphinx-copybutton", + "sphinx_reredirects", "nbsphinx>=0.9.4", "reno>=4.1", ] diff --git a/qiskit_addon_sqd/__init__.py b/qiskit_addon_sqd/__init__.py index 998ffe9..e872c06 100644 --- a/qiskit_addon_sqd/__init__.py +++ b/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.""" diff --git a/qiskit_addon_sqd/configuration_recovery.py b/qiskit_addon_sqd/configuration_recovery.py index 98ea929..3d81a55 100644 --- a/qiskit_addon_sqd/configuration_recovery.py +++ b/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 diff --git a/qiskit_addon_sqd/counts.py b/qiskit_addon_sqd/counts.py index 099b891..a996c87 100644 --- a/qiskit_addon_sqd/counts.py +++ b/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 diff --git a/qiskit_addon_sqd/fermion.py b/qiskit_addon_sqd/fermion.py index d11cc86..d14f721 100644 --- a/qiskit_addon_sqd/fermion.py +++ b/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 diff --git a/qiskit_addon_sqd/qubit.py b/qiskit_addon_sqd/qubit.py index b84ee2e..54ad6e9 100644 --- a/qiskit_addon_sqd/qubit.py +++ b/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 diff --git a/qiskit_addon_sqd/subsampling.py b/qiskit_addon_sqd/subsampling.py index 169078d..d603768 100644 --- a/qiskit_addon_sqd/subsampling.py +++ b/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