From 0ecc2448f416249d498ccc1c39c5c04bddf58b7d Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Mon, 4 Nov 2024 11:46:50 -0500
Subject: [PATCH] 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         | 33 +++++++++++++++
 .../class_no_inherited_members.rst            | 41 -------------------
 .../qiskit_addon_cutting.instructions.rst     |  8 +++-
 docs/apidocs/qiskit_addon_cutting.qpd.rst     | 14 ++++---
 ..._addon_cutting.utils.transpiler_passes.rst |  8 +++-
 docs/conf.py                                  | 16 ++++----
 .../utils/observable_grouping.py              |  6 +--
 tox.ini                                       |  9 +++-
 8 files changed, 71 insertions(+), 64 deletions(-)
 create mode 100644 docs/_templates/autosummary/class.rst
 delete mode 100644 docs/_templates/autosummary/class_no_inherited_members.rst

diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst
new file mode 100644
index 000000000..175b08f69
--- /dev/null
+++ 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/_templates/autosummary/class_no_inherited_members.rst b/docs/_templates/autosummary/class_no_inherited_members.rst
deleted file mode 100644
index 40ec64bcb..000000000
--- a/docs/_templates/autosummary/class_no_inherited_members.rst
+++ /dev/null
@@ -1,41 +0,0 @@
-{#
-   This is a copy of the default class template from the sphinx repository,
-   with a few minor changes. First, we do not render any inherited members.
-   Since we don't generate any inherited members, we include a show-inheritance
-   call to give users an indication there may be inherited class members.
-   Additionally, we also prevent duplication of the __init__ method by removing it
-   from the automethod call in the default.
--#}
-
-{{ fullname | escape | underline}}
-
-.. currentmodule:: {{ module }}
-
-.. autoclass:: {{ objname }}
-   :show-inheritance:
-
-   {% block methods %}
-   {% if methods %}
-   .. rubric:: {{ _('Methods') }}
-
-   .. autosummary::
-   {% for item in methods %}
-   {%- if item not in inherited_members %}
-      ~{{ name }}.{{ item }}
-   {%- endif %}
-   {%- endfor %}
-   {% endif %}
-   {% endblock %}
-
-   {% block attributes %}
-   {% if attributes %}
-   .. rubric:: {{ _('Attributes') }}
-
-   .. autosummary::
-   {% for item in attributes %}
-   {%- if item not in inherited_members %}
-      ~{{ name }}.{{ item }}
-   {%- endif %}
-   {%- endfor %}
-   {% endif %}
-   {% endblock %}
diff --git a/docs/apidocs/qiskit_addon_cutting.instructions.rst b/docs/apidocs/qiskit_addon_cutting.instructions.rst
index e703fc6b5..483d78240 100644
--- a/docs/apidocs/qiskit_addon_cutting.instructions.rst
+++ b/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
diff --git a/docs/apidocs/qiskit_addon_cutting.qpd.rst b/docs/apidocs/qiskit_addon_cutting.qpd.rst
index 67f1eeb31..f0a0b0bbe 100644
--- a/docs/apidocs/qiskit_addon_cutting.qpd.rst
+++ b/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
diff --git a/docs/apidocs/qiskit_addon_cutting.utils.transpiler_passes.rst b/docs/apidocs/qiskit_addon_cutting.utils.transpiler_passes.rst
index 6c543c9b8..661ee6040 100644
--- a/docs/apidocs/qiskit_addon_cutting.utils.transpiler_passes.rst
+++ b/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
diff --git a/docs/conf.py b/docs/conf.py
index 980ab46e7..a68d764b9 100644
--- a/docs/conf.py
+++ b/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 = {
diff --git a/qiskit_addon_cutting/utils/observable_grouping.py b/qiskit_addon_cutting/utils/observable_grouping.py
index 8ab12c532..b0fd29c67 100644
--- a/qiskit_addon_cutting/utils/observable_grouping.py
+++ b/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`.
 
         """
diff --git a/tox.ini b/tox.ini
index bbd8b98b7..4e2eb24d6 100644
--- a/tox.ini
+++ b/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/