Move metadata, versions and specifiers API documentation to sphinx.ext.autodoc
#572
Conversation
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 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.
brettcannon
approved these changes
Jul 12, 2022
| platforms: list[str] | ||
| _canonical_name: NormalizedName | ||
| version: Version | ||
| platforms: List[str] |
There was a problem hiding this comment.
How did you get pre-commit to not change that thanks to pyupgrade running?
There was a problem hiding this comment.
I'm guessing it's the removal of from future import __annotations__.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Toward #567.
At the time of opening this PR, only three modules have been converted over --
metadata,versionandspecifiers. 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.