Show class members #702

Eric-Arellano · 2024-10-30T20:12:20Z

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

coveralls · 2024-10-30T20:14:36Z

Pull Request Test Coverage Report for Build 11667974979

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

For more information on this, see Tracking coverage changes with pull request builds.
To avoid this issue with future PRs, see these Recommended CI Configurations.
For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

0 of 0 changed or added relevant lines in 0 files are covered.
No unchanged relevant lines lost coverage.
Overall coverage remained the same at 100.0%

Totals
Change from base Build 11582107798:	0.0%
Covered Lines:	2330
Relevant Lines:	2330

💛 - Coveralls

Eric-Arellano · 2024-10-30T20:13:00Z

docs/_templates/autosummary/class.rst

@@ -0,0 +1,33 @@
+{#


This is copied from Qiskit SDK, other than where I comment. I'm probably going to update Qiskit to mirror this

Eric-Arellano · 2024-10-30T20:13:55Z

docs/_templates/autosummary/class.rst

+   :no-inherited-members:
+   :no-special-members:


We have to set this to avoid the methods being duplicated. That's because we configured .. autoclass in conf.py to now show inherited members

Eric-Arellano · 2024-10-30T20:14:23Z

docs/_templates/autosummary/class_no_inherited_members.rst

This was already unused

Eric-Arellano · 2024-10-30T20:14:42Z

docs/apidocs/qiskit_addon_cutting.qpd.rst


+.. autoclass:: WeightType


This class is tiny, so I think it's fine to keep inlined

Eric-Arellano · 2024-10-30T20:14:56Z

docs/conf.py

+napoleon_google_docstring = True
+napoleon_numpy_docstring = False


This is a performance enhancement for build-time

Eric-Arellano · 2024-10-30T20:15:10Z

qiskit_addon_cutting/utils/observable_grouping.py


        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.


The lack of - was causing a Sphinx error

qiskit_addon_cutting/utils/observable_grouping.py

garrison · 2024-11-04T14:08:24Z

tox.ini

+allowlist_externals =
+  rm
+commands =
+  rm -rf {toxinidir}/docs/stubs/ {toxinidir}/docs/_build/


This is fine, but also mostly noting: there is already some cleaning that goes on in the docs environment. We could potentially remove it with this.

Ack, I noticed that. It only deletes .doctrees inside html rather than the entire folder, however. I also think it's nice to have tox -e docs-clean to be consistent with the other addon repos - muscle memory.

Lmk if you want me to delete this though. I'm fine with that

Sorry, I meant that we could potentially remove those steps from the docs environment now that there is docs-clean.

Ah, yeah I agree. There are many times where you do want the caching to be preserved. Updated

garrison

This looks good to me

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 (cherry picked from commit 0ecc244)

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 (cherry picked from commit 0ecc244) Co-authored-by: Eric Arellano <[email protected]>

Show class members

add8b7c

Eric-Arellano added the stable backport potential Suitable to be backported to most recent stable branch by Mergify label Oct 30, 2024

Eric-Arellano requested review from garrison and caleb-johnson October 30, 2024 20:12

Eric-Arellano commented Oct 30, 2024

View reviewed changes

garrison reviewed Nov 4, 2024

View reviewed changes

garrison previously approved these changes Nov 4, 2024

View reviewed changes

tox -e docs does not remove files

6ae9597

Eric-Arellano dismissed garrison’s stale review via 6ae9597 November 4, 2024 16:02

garrison approved these changes Nov 4, 2024

View reviewed changes

Eric-Arellano merged commit 0ecc244 into Qiskit:main Nov 4, 2024
11 checks passed

Eric-Arellano deleted the EA/show-class-members branch November 4, 2024 16:47

mergify bot mentioned this pull request Nov 4, 2024

Show class members (backport #702) #707

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Show class members #702

Show class members #702

Eric-Arellano commented Oct 30, 2024

coveralls commented Oct 30, 2024 •

edited

Loading

Eric-Arellano Oct 30, 2024

Eric-Arellano Oct 30, 2024

Eric-Arellano Oct 30, 2024

Eric-Arellano Oct 30, 2024

Eric-Arellano Oct 30, 2024

Eric-Arellano Oct 30, 2024

garrison Nov 4, 2024

Eric-Arellano Nov 4, 2024

garrison Nov 4, 2024

Eric-Arellano Nov 4, 2024

garrison left a comment

		napoleon_google_docstring = True
		napoleon_numpy_docstring = False

Show class members #702

Show class members #702

Conversation

Eric-Arellano commented Oct 30, 2024

coveralls commented Oct 30, 2024 • edited Loading

Pull Request Test Coverage Report for Build 11667974979

Warning: This coverage report may be inaccurate.

Details

💛 - Coveralls

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

garrison left a comment

Choose a reason for hiding this comment

coveralls commented Oct 30, 2024 •

edited

Loading