-
Notifications
You must be signed in to change notification settings - Fork 571
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
docs: switch to sphinx-autodoc-typehints #1854
docs: switch to sphinx-autodoc-typehints #1854
Conversation
Will rebase and publish after merging #1825 |
963dee1
to
953aa1b
Compare
953aa1b
to
5ca45ef
Compare
marking as draft so I can fix warnings. |
5ca45ef
to
6e235bc
Compare
Difference illustrated below:
Again, the reason why |
Currently rdflib is relying on sphinx-autodoc's built in handling for type hints, this however has some deficiencies as it does not handle stuff inside `if TYPE_CHECKING:` and thus only work in cases where there are no potential for circular dependencies. This patch changes sphinx to use sphinx-autodoc-typehints instead, the documentation generated by this plugin looks slightly different but as a positive it correctly works with things defined inside `if TYPE_CHECKING:` guards. Also: - moved the `_NamespaceSetString` type alias to `rdflib._type_checking` This is so that `sphinx-autodoc-typehints` recognizes it up, as it does not handle type aliases that are defined inside `if TYPE_CHECKING:` guards in imported files. - remove sphinx requirements from requirements.dev.txt and replaced it with -r docs/sphinx-requirements.txt to reduce redundancy.
6e235bc
to
af93d38
Compare
PR branch looks very nice and closer to what I conceive of as a "typical" programming model, i.e. what one would reference when documenting or authoring HOW-TOs. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
good plug in use!
Summary of changes
Currently rdflib is relying on sphinx-autodoc's built in handling for type
hints, this however has some deficiencies as it does not handle stuff
inside
if TYPE_CHECKING:
and thus only work in cases where there are nopotential for circular dependencies.
This patch changes sphinx to use sphinx-autodoc-typehints instead, the
documentation generated by this plugin looks slightly different but as a
positive it correctly works with things defined inside
if TYPE_CHECKING:
guards.
Also:
_NamespaceSetString
type alias tordflib._type_checking
This is so that
sphinx-autodoc-typehints
recognizes it up, as itdoes not handle type aliases that are defined inside
if TYPE_CHECKING:
guards in imported files.requirements.dev.txt
andreplaced it with
-r docs/sphinx-requirements.txt
to reduce redundancy.Checklist
the same change.
so maintainers can fix minor issues and keep your PR up to date.