Show class members (#702)

We weren't showing class members (attributes & methods) for inlined classes. This is fixed by setting `"inherited-members": None` in `autodoc_default_options`. 

Notably, we now show inherited members for classes like `instructions.Move`. I recommend this because users want to know every function/attribute defined on the object, and they don't really care about the origin of that functionality. Qiskit SDK takes this approach, which is useful with e.g. the circuit library.

With this change, some of the classes end up being much larger. So, we un-inline them and move them back to being their own pages in `stubs/`. This means we remove their client redirects.

This PR also makes some other enhancements:

* Adds `tox -e docs-clean`
* Displays type hints in the `parameters` section, rather than inline to the signature. This matches the style of the other API projects

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 %}

docs/apidocs/qiskit_addon_cutting.instructions.rst

@@ -9,5 +9,9 @@ Instructions (:mod:`qiskit_addon_cutting.instructions`)
 
 .. currentmodule:: qiskit_addon_cutting.instructions
 
-.. autoclass:: CutWire
-.. autoclass:: Move
+.. autosummary::
+   :nosignatures:
+   :toctree: ../stubs/
+
+   CutWire
+   Move

docs/apidocs/qiskit_addon_cutting.qpd.rst

@@ -9,12 +9,16 @@ Quasi-Probability Decomposition (QPD) (:mod:`qiskit_addon_cutting.qpd`)
 
 .. currentmodule:: qiskit_addon_cutting.qpd
 
-.. autoclass:: QPDBasis
-.. autoclass:: BaseQPDGate
-.. autoclass:: SingleQubitQPDGate
-.. autoclass:: TwoQubitQPDGate
-.. autoclass:: WeightType
+.. autosummary::
+   :nosignatures:
+   :toctree: ../stubs/
+
+   QPDBasis
+   BaseQPDGate
+   SingleQubitQPDGate
+   TwoQubitQPDGate
 
+.. autoclass:: WeightType
 .. autofunction:: generate_qpd_weights
 .. autofunction:: decompose_qpd_instructions
 .. autofunction:: qpdbasis_from_instruction

docs/apidocs/qiskit_addon_cutting.utils.transpiler_passes.rst

@@ -9,5 +9,9 @@ Transpiler passes (:mod:`qiskit_addon_cutting.utils.transpiler_passes`)
 
 .. currentmodule:: qiskit_addon_cutting.utils.transpiler_passes
 
-.. autoclass:: RemoveFinalReset
-.. autoclass:: ConsolidateResets
+.. autosummary::
+   :nosignatures:
+   :toctree: ../stubs/
+
+   RemoveFinalReset
+   ConsolidateResets

docs/conf.py

@@ -83,10 +83,16 @@
 html_static_path = ["_static"]
 html_css_files = ["css/custom.css"]
 
-# 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,
+}
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
 
 # nbsphinx options (for tutorials)
 nbsphinx_timeout = 180
@@ -132,12 +138,6 @@
     ("qiskit_addon_cutting", "find_cuts"),
     ("qiskit_addon_cutting", "OptimizationParameters"),
     ("qiskit_addon_cutting", "DeviceConstraints"),
-    ("qiskit_addon_cutting.instructions", "CutWire"),
-    ("qiskit_addon_cutting.instructions", "Move"),
-    ("qiskit_addon_cutting.qpd", "QPDBasis"),
-    ("qiskit_addon_cutting.qpd", "BaseQPDGate"),
-    ("qiskit_addon_cutting.qpd", "SingleQubitQPDGate"),
-    ("qiskit_addon_cutting.qpd", "TwoQubitQPDGate"),
     ("qiskit_addon_cutting.qpd", "WeightType"),
     ("qiskit_addon_cutting.qpd", "generate_qpd_weights"),
     ("qiskit_addon_cutting.qpd", "decompose_qpd_instructions"),
@@ -155,8 +155,6 @@
     ("qiskit_addon_cutting.utils.simulation", "ExactSampler"),
     ("qiskit_addon_cutting.utils.transforms", "separate_circuit"),
     ("qiskit_addon_cutting.utils.transforms", "SeparatedCircuits"),
-    ("qiskit_addon_cutting.utils.transpiler_passes", "RemoveFinalReset"),
-    ("qiskit_addon_cutting.utils.transpiler_passes", "ConsolidateResets"),
 ]
 
 redirects = {

qiskit_addon_cutting/utils/observable_grouping.py

@@ -250,13 +250,13 @@ def groups(self) -> list[CommutingObservableGroup]:
 
     @property
     def lookup(self) -> dict[Pauli, list[tuple[int, int]]]:
-        r"""Get dict which maps each :class:`~qiskit.quantum_info.Pauli` observable to a list of indices, ``(i, j)``, to commuting observables in ``groups``.
+        """Get dict which maps each :class:`~qiskit.quantum_info.Pauli` observable to a list of indices, ``(i, j)``, to commuting observables in ``groups``.
 
         For each element of the list, it means that the :class:`~qiskit.quantum_info.Pauli` is given by
-        the ``j``th commuting observable in the ``i``th group.
+        the ``j``-th commuting observable in the ``i``-th group.
 
         This list will be of length 1 at minimum, but may potentially be longer
-        if multiple :class:`.CommutingObservableGroup`\ s are compatible with the given
+        if multiple :class:`.CommutingObservableGroup` objects are compatible with the given
         :class:`~qiskit.quantum_info.Pauli`.
 
         """

tox.ini

@@ -54,8 +54,13 @@ extras =
   docs
   notebook-dependencies
 commands =
-  python -c 'import shutil, pathlib; shutil.rmtree(pathlib.Path("docs") / "stubs", ignore_errors=True)'
-  python -c 'import shutil, pathlib; shutil.rmtree(pathlib.Path("docs") / "_build" / "html" / ".doctrees", ignore_errors=True)'
   sphinx-build -j auto -W -T --keep-going {posargs} docs/ docs/_build/html
 passenv =
   CI
+
+[testenv:docs-clean]
+skip_install = true
+allowlist_externals =
+  rm
+commands =
+  rm -rf {toxinidir}/docs/stubs/ {toxinidir}/docs/_build/