Improve Package Exposure in Documentaiton #878
Conversation
…nflict with decorator `particle_input` in the documentation.
…ssing index for the `plasmapy` module)
…ge members; add __all__; explicitly import all sub-packages; organize imports;
…y has non-public api
rocco8773
added
docs
…smapy.utils.pytest_helpers that are not autodoc-ed in the narrative documentation
…smapy.utils.roman that are not autodoc-ed in the narrative documentation
…smapy.conftest and plasmapy.optional_deps that are not autodoc-ed in the narrative documentation
|
@StanczakDominik I don't understand the errors we're getting with azure piplines now. It always seems to be on py36_windows, but where the error happens does not seem to be consistent. It does seems to correspond with an import of
|
|
Sure, I'll get to it later in the day. Get some sleep! :) |
|
Looks like the pipelines fixed themselves. After a little reading, I think the fails could be due to either circular imports or pushing new commits too frequently, which interrupts the last build and causes issues for the new build. I'm not confident with either of those solutions, but I'll take that they're passing now. |
|
Gah, I ended up literally sleeping through it (I blame the blueberry pie) and now this ended up reinforcing my procrastinatory habits :( I'll look through it tomorrow. |
| :orphan: | ||
|
|
||
| `plasmapy.conftest` | ||
| =================== | ||
|
|
||
| .. currentmodule:: plasmapy.conftest | ||
|
|
||
| .. automodapi:: plasmapy.conftest | ||
| :include-all-objects: | ||
| :no-heading: |
There was a problem hiding this comment.
I was surprised to see what I see as essentially a pytest config file documented. But sure, there's no harm in putting it in here.
There was a problem hiding this comment.
Yeah, I debated this, along with documenting private members. I deferred the decision on the later due to automodapi not having convenient mechanisms for this. I included the module because I thought it might be useful for contributors down the road.
Co-authored-by: Dominik Stańczak <[email protected]>
… improve-pkg-exposure-in-docs
|
@StanczakDominik I don't plan on making anymore changes, so you can merge whenever you like. Not sure if we want to get @namurphy's feedback first. @namurphy do you have anything to say about this? @StanczakDominik I'm assuming you want to merge this PR before #857, correct? |
Preferably, yeah! I think Nick was broadly on the 👍 side during the last telecon for the main idea behind these changes, so I think it should be fine to merge it now. |
|
Do it! You have the honors. :) Thanks for the review! |
This is a long needed update to the documentation that increases the document exposure of the
plamsapypackage. Currently there is functionality in the package whose docstrings do not make it into the documentation build. This is primarily due the fact that many package elements do not go through thesphinxautodocdirectives during our narrative documentation.This PR manually creates reST files for the package elements that are not
autodoc-ed in our narrative documentation. These reST files are placed in a newly created/docs/api_staticdirectory (similar to the automatically generatedautomodapistub files in theapidirectory).This has no affect on our current narrative documentation, but improves the objects detected by
intersphinxand exposes all package members in thegenindexand/orpy-modindexlinks.I am also reviewing/adding docstrings to improve readability.