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 9f389c12e..7278984c6 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/