-
Notifications
You must be signed in to change notification settings - Fork 189
docs: Sphinx 9 and fix member skipping #2298
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
22 commits
Select commit
Hold shift + click to select a range
7c03c87
docs: WIP Sphinx 9
flying-sheep 0f1a220
Make protocols work
flying-sheep 0b2f2c8
patch sphinx-design
flying-sheep e4658d8
better comments
flying-sheep eeb3fd2
use public APIs
flying-sheep 4767d37
order
flying-sheep 817d71a
docs: skip inherited members without code
flying-sheep 087e6d5
improve jinja syntax
flying-sheep e8da5c1
no more override
flying-sheep 3069f68
Fix ABC members
flying-sheep 7572f0d
speedup
flying-sheep 9bc9828
Merge branch 'main' into pa/simple-skip-inherited
flying-sheep 4c4c06f
circumvent issue
flying-sheep c9fd9c4
add minimal template
flying-sheep 9ed78b5
Merge branch 'sphinx-9' into pa/simple-skip-inherited
flying-sheep 2764a28
some fixes
flying-sheep 673b294
fix overrides
flying-sheep 391dcc0
update scanpydoc
flying-sheep 6e385ca
yiss
flying-sheep 0a9b7ac
comment
flying-sheep d35d3e5
add inheritance
flying-sheep b268c70
fix type
flying-sheep File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| {{ fullname | escape | underline}} | ||
|
|
||
| .. currentmodule:: {{ module }} | ||
|
|
||
| .. autoclass:: {{ objname }} | ||
| :show-inheritance: | ||
|
|
||
| {% block attributes %} | ||
| {%- for item in attributes %} | ||
| {%- if loop.first %} | ||
| .. rubric:: Attributes | ||
| {% endif %} | ||
| .. autoattribute:: {{ item }} | ||
| {%- endfor %} | ||
| {% endblock %} | ||
|
|
||
| {% block methods %} | ||
| {%- for item in methods if item != "__init__" and item not in inherited_members %} | ||
| {%- if loop.first %} | ||
| .. rubric:: Methods | ||
| {% endif %} | ||
| .. automethod:: {{ item }} | ||
| {%- endfor %} | ||
| {% endblock %} |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,28 +1,58 @@ | ||
| """Sphinx extension to not skip abstract methods.""" | ||
| """Sphinx extension to not skip abstract/protocol methods.""" | ||
|
|
||
| from __future__ import annotations | ||
|
|
||
| import abc | ||
| import sys | ||
| from traceback import walk_stack | ||
| from typing import TYPE_CHECKING | ||
|
|
||
| if TYPE_CHECKING: | ||
| from typing import Literal | ||
| if sys.version_info >= (3, 13): | ||
| from typing import get_protocol_members, is_protocol | ||
| else: | ||
| from typing_extensions import get_protocol_members, is_protocol | ||
|
|
||
| if TYPE_CHECKING: | ||
| from sphinx.application import Sphinx | ||
| from sphinx.ext.autodoc import Options | ||
| from sphinx.ext.autodoc._property_types import _AutodocObjType | ||
|
|
||
|
|
||
| def autodoc_skip_member( # noqa: PLR0917 | ||
| def no_skip_abc_members( # noqa: PLR0917 | ||
| app: Sphinx, | ||
| what: Literal["module", "class", "exception", "function", "method", "attribute"], | ||
| what: _AutodocObjType, | ||
| name: str, | ||
| obj: object, | ||
| skip: bool, # noqa: FBT001 | ||
| options: Options, | ||
| ): | ||
| if what == "method" and getattr(obj, "__isabstractmethod__", False): | ||
| ) -> bool | None: | ||
| if what in {"module", "class", "exception", "decorator"}: | ||
| return None # speed up by not getting parent of non-class members | ||
|
|
||
| # Find parent class | ||
| for frame, _ in walk_stack(None): | ||
| if frame.f_code.co_name == "_get_members" and frame.f_code.co_filename.endswith( | ||
| "/generate.py" | ||
| ): | ||
| parent = frame.f_locals["obj"] | ||
| if not isinstance(parent, type): | ||
| return None | ||
| break | ||
| else: | ||
| return None | ||
|
|
||
| # Don’t skip abstract methods or properties | ||
| if issubclass(type(parent), abc.ABCMeta) and getattr( | ||
| obj, "__isabstractmethod__", False | ||
| ): | ||
| return False | ||
|
|
||
| # If we’re documenting a protocol attribute, include it | ||
| if is_protocol(parent) and name in get_protocol_members(parent): | ||
| return False | ||
|
|
||
| return None | ||
|
|
||
|
|
||
| def setup(app: Sphinx): | ||
| app.connect("autodoc-skip-member", autodoc_skip_member) | ||
| def setup(app: Sphinx) -> None: | ||
| app.connect("autodoc-skip-member", no_skip_abc_members) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| from __future__ import annotations | ||
|
|
||
| from typing import TYPE_CHECKING, Generic, get_origin | ||
|
|
||
| if TYPE_CHECKING: | ||
| from sphinx.application import Sphinx | ||
|
|
||
|
|
||
| def skip_private_bases( | ||
| app: Sphinx, name: str, obj: type, _unused, bases: list[type] | ||
| ) -> None: | ||
| bases[:] = [ | ||
| b | ||
| for b in bases | ||
| if b is not object | ||
| if get_origin(b) is not Generic | ||
| if not b.__name__.startswith("_") | ||
| ] | ||
|
|
||
|
|
||
| def setup(app: Sphinx) -> None: | ||
| app.connect("autodoc-process-bases", skip_private_bases) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.