Reorganize docs (#29)

* Reorganize docs * Better handle dynamic dispatch * Apply my suggestions from code review * Move `generate_ansatz_from_circuit` doc to ansatz_generation page * Fix title overline * Remove root doc page --------- Co-authored-by: Jim Garrison <[email protected]> Co-authored-by: Jim Garrison <[email protected]>
Qiskit · Nov 13, 2024 · d0f790a · d0f790a
1 parent 20c65c9
commit d0f790a
Show file tree

Hide file tree

Showing 15 changed files with 186 additions and 84 deletions.
diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst
@@ -0,0 +1,33 @@
+{#
+   We show all the class's methods and attributes on the same page. By default, we document
+   all methods, including those defined by parent classes.
+-#}
+
+{{ objname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
+   :show-inheritance:
+
+{% block attributes_summary %}
+  {% if attributes %}
+   .. rubric:: Attributes
+    {% for item in attributes %}
+   .. autoattribute:: {{ item }}
+    {%- endfor %}
+  {% endif %}
+{% endblock -%}
+
+{% block methods_summary %}
+  {% set wanted_methods = (methods | reject('==', '__init__') | list) %}
+  {% if wanted_methods %}
+   .. rubric:: Methods
+    {% for item in wanted_methods %}
+   .. automethod:: {{ item }}
+    {%- endfor %}
+  {% endif %}
+{% endblock %}
diff --git a/docs/apidocs/ansatz_generation.rst b/docs/apidocs/ansatz_generation.rst
@@ -1,10 +1,22 @@
-.. _ansatz_generation:
-
-#################
-Ansatz Generation
-#################
+####################################################################
+Ansatz generation (:mod:`qiskit_addon_aqc_tensor.ansatz_generation`)
+####################################################################
 
 .. automodule:: qiskit_addon_aqc_tensor.ansatz_generation
    :no-members:
    :no-inherited-members:
-   :no-special-members:
+   :no-special-members:
+
+.. currentmodule:: qiskit_addon_aqc_tensor.ansatz_generation
+
+.. autosummary::
+    :toctree: ../stubs/
+    :nosignatures:
+
+    AnsatzBlock
+    OneQubitAnsatzBlock
+    TwoQubitAnsatzBlock
+    ZXZ
+    KAK
+
+.. autofunction:: generate_ansatz_from_circuit
diff --git a/docs/apidocs/index.rst b/docs/apidocs/index.rst
@@ -1,14 +1,12 @@
-.. _aqctensor:
-
-.. module:: qiskit_addon_aqc_tensor
-
-========================
-AQC-Tensor API Reference
-========================
+=========================================
+``qiskit-addon-aqc-tensor`` API Reference
+=========================================
 
 .. toctree::
    :maxdepth: 1
 
    ansatz_generation
    objective
    simulation
+   simulation-aer
+   simulation-quimb
diff --git a/docs/apidocs/objective.rst b/docs/apidocs/objective.rst
@@ -1,10 +1,12 @@
-.. _objective:
-
-##################
-Objective Function
-##################
+################################################################
+Objective function(s) (:mod:`qiskit_addon_aqc_tensor.objective`)
+################################################################
 
 .. automodule:: qiskit_addon_aqc_tensor.objective
    :no-members:
    :no-inherited-members:
    :no-special-members:
+
+.. currentmodule:: qiskit_addon_aqc_tensor.objective
+
+.. autoclass:: OneMinusFidelity
diff --git a/docs/apidocs/simulation-aer.rst b/docs/apidocs/simulation-aer.rst
@@ -0,0 +1,20 @@
+######################################################################
+Aer simulation backend (:mod:`qiskit_addon_aqc_tensor.simulation.aer`)
+######################################################################
+
+.. automodule:: qiskit_addon_aqc_tensor.simulation.aer
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
+
+.. autosummary::
+    :toctree: ../stubs/
+    :nosignatures:
+
+    QiskitAerMPS
+    QiskitAerSimulationSettings
+
+Functions
+=========
+
+.. autofunction:: is_aer_available
diff --git a/docs/apidocs/simulation-quimb.rst b/docs/apidocs/simulation-quimb.rst
@@ -0,0 +1,24 @@
+##########################################################################
+Quimb simulation backend (:mod:`qiskit_addon_aqc_tensor.simulation.quimb`)
+##########################################################################
+
+.. automodule:: qiskit_addon_aqc_tensor.simulation.quimb
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
+
+.. autosummary::
+    :toctree: ../stubs/
+    :nosignatures:
+
+    QuimbCircuitFactory
+    QuimbSimulator
+    QiskitQuimbConversionContext
+
+Functions
+=========
+
+.. autofunction:: is_quimb_available
+.. autofunction:: qiskit_ansatz_to_quimb
+.. autofunction:: recover_parameters_from_quimb
+.. autofunction:: tnoptimizer_objective_kwargs
diff --git a/docs/apidocs/simulation.rst b/docs/apidocs/simulation.rst
@@ -1,10 +1,35 @@
-.. _simulation:
-
-#########################
-Tensor Network Simulation
-#########################
+#####################################################################
+Tensor network simulation (:mod:`qiskit_addon_aqc_tensor.simulation`)
+#####################################################################
 
 .. automodule:: qiskit_addon_aqc_tensor.simulation
    :no-members:
    :no-inherited-members:
    :no-special-members:
+
+.. currentmodule:: qiskit_addon_aqc_tensor.simulation
+
+Available backends
+==================
+
+* :mod:`qiskit_addon_aqc_tensor.simulation.aer`
+* :mod:`qiskit_addon_aqc_tensor.simulation.quimb`
+
+Functions
+=========
+
+The following functions provide a common interface that can be used with any supported backend. Regardless of which backend you use, you will invoke these functions as a common interface.
+
+In each function below, the documentation shows every distinct implementation available for that function. The addon will choose which implementation to use based on the types of the arguments that you provide. (This paradigm is called "multiple dispatch".)
+
+.. autofunction:: tensornetwork_from_circuit
+.. autofunction:: apply_circuit_to_state
+.. autofunction:: compute_overlap
+
+Abstract classes
+================
+
+These are abstract classes, implemented by each backend.
+
+.. autoclass:: TensorNetworkState
+.. autoclass:: TensorNetworkSimulationSettings
diff --git a/docs/conf.py b/docs/conf.py
@@ -71,9 +71,18 @@
 html_static_path = ["_static"]
 templates_path = ["_templates"]
 
-# autodoc/autosummary options
+# Options for autodoc. These reflect the values from Qiskit SDK and Runtime.
 autosummary_generate = True
 autosummary_generate_overwrite = False
+autoclass_content = "both"
+autodoc_typehints = "description"
+autodoc_default_options = {
+    "inherited-members": None,
+    "show-inheritance": True,
+}
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+
 
 # nbsphinx options (for tutorials)
 nbsphinx_timeout = 180
@@ -90,8 +99,27 @@
 plot_html_show_formats = False
 plot_formats = ["svg"]
 
-# Redirects for pages that have moved
-redirects = {}
+# ----------------------------------------------------------------------------------
+# Redirects
+# ----------------------------------------------------------------------------------
+
+_inlined_apis = [
+    ("qiskit_addon_aqc_tensor.objective", "OneMinusFidelity"),
+    ("qiskit_addon_aqc_tensor.simulation", "TensorNetworkState"),
+    ("qiskit_addon_aqc_tensor.simulation", "TensorNetworkSimulationSettings"),
+    ("qiskit_addon_aqc_tensor.simulation", "tensornetwork_from_circuit"),
+    ("qiskit_addon_aqc_tensor.simulation", "apply_circuit_to_state"),
+    ("qiskit_addon_aqc_tensor.simulation", "compute_overlap"),
+]
+
+redirects = {
+    "stubs/qiskit_addon_aqc_tensor.ansatz_generation.generate_ansatz_from_circuit": "../apidocs/qiskit-addon-aqc-tensor.html#qiskit_addon_aqc_tensor.generate_ansatz_from_circuit",
+    **{
+        f"stubs/{module}.{name}": f"../apidocs/{module.split('.')[-1]}.html#{module}.{name}"
+        for module, name in _inlined_apis
+    },
+}
+
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
@@ -104,7 +132,7 @@
     ),
     "qiskit-aer": ("https://qiskit.github.io/qiskit-aer/", None),
     "rustworkx": ("https://www.rustworkx.org/", None),
-    "qiskit_addon_utils": ("https://qiskit.github.io/qiskit-addon-utils/", None),
+    "qiskit_addon_utils": ("https://docs.quantum.ibm.com/api/qiskit-addon-utils/", None),
     "quimb": ("https://quimb.readthedocs.io/en/latest/", None),
 }
 
@@ -182,4 +210,4 @@ def is_valid_code_object(obj):
     else:
         ending_lineno = lineno + len(source) - 1
         linespec = f"#L{lineno}-L{ending_lineno}"
-    return f"https://github.com/Qiskit/qiskit-addon-aqc_tensor/tree/{GITHUB_BRANCH}/qiskit_addon_aqc_tensor/{file_name}{linespec}"
+    return f"https://github.com/Qiskit/qiskit-addon-aqc-tensor/tree/{GITHUB_BRANCH}/qiskit_addon_aqc_tensor/{file_name}{linespec}"
diff --git a/qiskit_addon_aqc_tensor/__init__.py b/qiskit_addon_aqc_tensor/__init__.py
@@ -24,6 +24,7 @@
     # Package is not installed
     pass
 
+# Reminder: update the RST file in docs/apidocs when adding new interfaces.
 __all__ = [
     "generate_ansatz_from_circuit",
 ]
diff --git a/qiskit_addon_aqc_tensor/ansatz_generation.py b/qiskit_addon_aqc_tensor/ansatz_generation.py
@@ -9,16 +9,9 @@
 # Any modifications or derivative works of this code must retain this
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
-"""Utility for generating a general, parametrized, ansatz circuit which matches the two-qubit connectivity of an input circuit.
 
-.. currentmodule:: qiskit_addon_aqc_tensor.ansatz_generation
-
-.. autosummary::
-    :toctree: ../stubs/
-    :nosignatures:
-
-    generate_ansatz_from_circuit
-"""
+# Reminder: update the RST file in docs/apidocs when adding new interfaces.
+"""Utility for generating a general, parametrized, ansatz circuit which matches the two-qubit connectivity of an input circuit."""
 
 from __future__ import annotations
 
@@ -279,6 +272,7 @@ def perform_separation(q0: int, q1: int):
     return ansatz, initial_params
 
 
+# Reminder: update the RST file in docs/apidocs when adding new interfaces.
 __all__ = [
     "generate_ansatz_from_circuit",
     "AnsatzBlock",

diff --git a/qiskit_addon_aqc_tensor/objective.py b/qiskit_addon_aqc_tensor/objective.py
@@ -9,17 +9,10 @@
 # Any modifications or derivative works of this code must retain this
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
+
 """Code for building and evaluating objective functions used for AQC parameter optimization.
 
 Currently, this module provides the simplest possible objective function, :class:`.OneMinusFidelity`.
-
-.. currentmodule:: qiskit_addon_aqc_tensor.objective
-
-.. autosummary::
-    :toctree: ../stubs/
-    :nosignatures:
-
-    OneMinusFidelity
 """
 
 from __future__ import annotations
@@ -92,6 +85,7 @@ def target(self) -> TensorNetworkState:
         return self._target_tensornetwork
 
 
+# Reminder: update the RST file in docs/apidocs when adding new interfaces.
 __all__ = [
     "OneMinusFidelity",
 ]
diff --git a/qiskit_addon_aqc_tensor/simulation/__init__.py b/qiskit_addon_aqc_tensor/simulation/__init__.py
@@ -13,43 +13,6 @@
 """This module provides an interface to tensor-network simulation that is agnostic to which backend is used.
 
 Currently, there is a single implementation, which uses the Qiskit Aer matrix-product state (MPS) simulator as its backend.
-
-Abstract classes
-----------------
-
-.. currentmodule:: qiskit_addon_aqc_tensor.simulation
-
-.. autosummary::
-    :toctree: ../stubs/
-    :nosignatures:
-
-    TensorNetworkState
-    TensorNetworkSimulationSettings
-
-Aer backend (:mod:`qiskit_addon_aqc_tensor.simulation.aer`)
-
-.. currentmodule:: qiskit_addon_aqc_tensor.simulation.aer
-
-.. autosummary::
-    :toctree: ../stubs/
-    :nosignatures:
-
-    QiskitAerMPS
-    QiskitAerSimulationSettings
-
-Methods.
-
-The following abstract methods provide a common interface that can be used with any supported backend:
-
-.. currentmodule:: qiskit_addon_aqc_tensor.simulation
-
-.. autosummary::
-    :toctree: ../stubs/
-    :nosignatures:
-
-    tensornetwork_from_circuit
-    apply_circuit_to_state
-    compute_overlap
 """
 
 # We must import each tensor-network backend we wish to use so that their
@@ -67,6 +30,7 @@
 _ = aer
 __ = quimb
 
+# Reminder: update the RST file in docs/apidocs when adding new interfaces.
 __all__ = [
     "TensorNetworkState",
     "TensorNetworkSimulationSettings",

diff --git a/qiskit_addon_aqc_tensor/simulation/aer/__init__.py b/qiskit_addon_aqc_tensor/simulation/aer/__init__.py
@@ -26,6 +26,7 @@
 # import so the linter does not complain.
 _ = _preprocess_for_gradient
 
+# Reminder: update the RST file in docs/apidocs when adding new interfaces.
 __all__ = [
     "is_aer_available",
     "QiskitAerMPS",

diff --git a/qiskit_addon_aqc_tensor/simulation/quimb/__init__.py b/qiskit_addon_aqc_tensor/simulation/quimb/__init__.py
@@ -405,6 +405,7 @@ def oneminusfidelity_loss_fn(
     return 1 - fidelity
 
 
+# Reminder: update the RST file in docs/apidocs when adding new interfaces.
 __all__ = [
     "is_quimb_available",
     "QuimbCircuitFactory",