-
Notifications
You must be signed in to change notification settings - Fork 252
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
Move metadata
, versions
and specifiers
API documentation to sphinx.ext.autodoc
#572
Conversation
This is the style of organisation within the conf.py file that is used in newer Sphinx versions.
If we need it, we can add it in later.
The migration from modern annotations (thanks to a `__future__` import) to the plain typing-import based annotations is to deal with limitations of intersphinx with autodoc, which currently can't linkify annotations with future style imports. Similarly, to make the type annotations in the generated documentation correctly link to the various "internal" types, they need to be imported and referenced by their regular name instead of a changed-name import. In the spirit of consistency, all imports were changed to match this style. This allows for eliminating duplication of content in the implementation and documentation, reducing the general maintainance overhead of this module.
Oops, I missed a closing bracket in one of the examples. I'll come around to it, after someone takes a look at this. :) |
Moving the content into inline docstrings makes it easier to ensure that they are updated/evolve with the implementation. This also expands the behaviors shown, by documenting the relevant details for each function. These examples are doctest'd in CI.
Moving the content into inline docstrings makes it easier to ensure that they are updated/evolve with the implementation. This also expands the behaviors shown, by documenting the relevant details for each function. These examples are doctest'd in CI.
platforms: list[str] | ||
_canonical_name: NormalizedName | ||
version: Version | ||
platforms: List[str] |
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.
How did you get pre-commit to not change that thanks to pyupgrade running?
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.
I'm guessing it's the removal of from future import __annotations__
.
Toward #567.
At the time of opening this PR, only three modules have been converted over --
metadata
,version
andspecifiers
. I'd like to get a round of feedback on this, before moving forward on the other modules (I'm adding example usage to make the various concepts clearer and that is taking a decent amount of time!).I think it's reasonable to do this incrementally, so we can handle the other modules once we have agreement that this is a positive direction to take things. :)
PS: Some code moved up-and-down in the class bodies, since I've configured autodoc ordering to be
"bysource"
. It might make sense to do"groupwise"
instead, but I prefer this since it gives us more control on ordering.