-
Notifications
You must be signed in to change notification settings - Fork 339
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
A version of automodapi for PlasmaPy #1105
Conversation
…) and implement in GenDocFromAutomodsumm
… based on autosumm options; incorporate mod_objs_option_filtered into generate_obj_list; add some typing
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.
The mobile app is not letting me do a single line comment for some reason.
docs/automodapi/__init__.py
Outdated
@@ -0,0 +1,18 @@ | |||
# The code here was adapted from v0.14.0.dev0 of sphinx_automodapi |
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 note the license of automodapi here! Also, dev0 is probably autogenerated and it'd be better to point to a particular commit.
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.
There is still a lot of clean up to be had here and there, including properly linking to sphinx_automodapi
. I just want to get the bulk working and then I'll go back to dot the i's and cross the t's.
@StanczakDominik I'm not exactly sure why the tests are failing. I believe the runner currently thinks it has to run tests on any |
Sure, I'll get them passing :) don't worry about it. |
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.
A partial review focusing on docstrings in __init__.py
and automodapi.py
. Looks like there is some really useful functionality in there. The suggestions are pretty minor. In a few places I wasn't sure if my suggestion referred to what you intended so feel free to adjust as needed. And thank you again for doing this!
`automodapi` Configuration Values | ||
--------------------------------- |
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.
There is a lot of useful functionality in this section!
Some notations are a bit puzzling. For example, the open bracket below seems to need a term before the comma, but none is there. What is meant by this notation? Alfven_speed(B, density[, ion, z_mean]) |
I also noticed that there was a thing on this page:
I'm not sure if there should be a comma or a space after the |
@rebeccaringuette and @namurphy When a the signature of a documented function shows parameters in square brackets, then those parameters are "optional" parameters. This is the behavior of Sphinx's
You can see this throughout documentation for various Python packages. For example, python's |
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.
Well, I've read the docs, fixed a few small typos. LveryGTM, I'd be in favor of a swift merge :)
This PR creates the sphinx extension package
plasmapy_sphinx
. This package defines two reST directivesautomodapi
andautomodsumm
, which are an adaption of the likely named directives fromsphinx_automdoapi
. There are a few significant distinctions of our directives over thesphinx_automodapi
directives that made me add the code here and not push it upstream tosphinx_automodapi
.I introduced the concept of groups for the directives. So, when an module is inspected for its objects, the found objects are categorized into group types (modules, functions, classes, exceptions, etc.). As a result, the
sphinx_automodapi
options like:functions-only:
are replaced by:groups: functions
.This move to the groups options allows for multiple groups to be displayed at once for
automodsumm
by doingIt additionally allows for custom groups to be defined.
Configuration values (that are defined in
conf.py
) are introduced that allows you define custom groups. To define a custom group theautomodapi_custom_groups
configuration value needs to be defined likeIn this example
mygroup
would be the name of the custom group,"title"
would be the title rendered above theautosummary
table whenautomodapi
is used, and"dunder"
is the name of the dunder variable used to list the custom group objects. This__mygroup__
would be placed in the module being documented with the custom group and is defined just like__all__
.The
automodapi
directive is an officialautodoc
directive and not a function connected to thesource-read
event. This allowsautomodapi
to benefit from all the default functionality associated with theautodoc
directives.