-
Notifications
You must be signed in to change notification settings - Fork 115
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
Use mkdocstring syntax for code-api generation #5892
Use mkdocstring syntax for code-api generation #5892
Conversation
1fc671f
to
48ec098
Compare
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.
Great work so far.
pulpcore/plugin/tasking.py
Outdated
@@ -13,3 +13,18 @@ | |||
reclaim_space, | |||
) | |||
from pulpcore.app.tasks.repository import add_and_remove # noqa: F401 |
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.
If we do the __all__
thing. we don't need the noqa: F401
anymore.
``` | ||
::: pulpcore.plugin.stages.ContentSaver | ||
options: | ||
filters: ["!_pre_save", "!_post_save"] |
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.
Should we add the filter "!_*" to the mkdoc config?
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.
Yes, probably
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.
@@ -9,83 +7,44 @@ to make writing sync code easier. There are several parts to the API: | |||
2. The builtin Stages including `artifact-stages` and `content-stages`. | |||
3. The `stages-api`, which allows you to build custom stages and pipelines. | |||
|
|||
|
|||
|
|||
## DeclarativeVersion |
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.
This whole file would be much shorter if we just called this section Reference and did ::: pulpcore.plugin.stages
.
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.
Yeah, but IHO these groupings are helpful.
The reference doc pages were using sphinx code-gen directives. This replaces those with mkdocstrings directives and tries to apply corresponding configurations where applicable. Closes: pulp#5834
84b5a93
to
a4a7850
Compare
The reason for this is because mkdocstrings requires this declaration to display imported members: https://mkdocstrings.github.io/python/usage/configuration/general/?h=import#preload_modules When we are using `__all__`, we could use star imports to avoid so much name duplication. Fixup: remove F401 when using __all__ and remove unecessary options
a4a7850
to
a5aceb5
Compare
The reference doc pages were using sphinx code-gen directives. This replaces those with mkdocstrings directives and tries to apply corresponding configurations where applicable.
To verify it works, you can serve this PR locally and skim through the subtree of:
pulpcore/docs/dev/reference/code-api/platform-api/
pulpcore/docs/dev/reference/code-api/plugins-api/
As noted in the second commit, the introduction of
__all__
is because mkdocstrings requires this declarationto display imported members.