Make documentation fully automatic #94
Conversation
* Patched in fixes for bugs in 1.2, which is now old enough to no longer be used.
* Python 3 uses different naming convention for the contents of the build directory, so change the pathing so that Sphinx can find the dbprocessing package in that directory.
* Bump to 1.3 for "needs" line; 1.2.4 doesn't exist, and 1.2.3 had bugs that were previously working around.
* Handling of javascript mods for the html changed, wasn't going to work in 3.0. Basically copied fix from readthedocs/sphinx_rtd_theme#728 * This was used for the "hide prompts" feature in example code. New version still works in 1.6, but no longer in 1.5 or earlier. Docs still render fine, just don't have the "hide" button, so this is okay.
* autoinstanceattribute changed, so update class template
* No special patching needed now, so tested on all released versions of sphinx, and remove check for maximum version supported.
* Added in 072fafe but never used.
* Just make sure there is at least a one-line at the top of each docstring so the autosummary table is populated properly. In a few cases docstrings were updated more specifically (particularly if there was none at all), but the goal is to get everything into the framework, not perfectly formatted.
jtniehof
added
the
documentation
|
My first look here is really good. One thing I have been experimenting with for other projects are the type annotations and sphinx really does a nice job with them. e.g. |
|
Type notes are python 3 (relatively recent, at that), so will wait until after get out first release and start ripping out Python 2 support. |
|
I keep getting this error when building the docs. Circle CI does not show anything. |
|
The reports import will fail if you don't have numpy or dateutil installed. The "runObj" error suggests you didn't run "Document or section may not begin with a transition" is probably a symptom of one of the other issues. Those warnings/errors will probably result in an empty document to which the epilog is appended, meaning it'll start with the horizonal rule that is supposed to be between the main body and that footer. So see if that still stays around when the others are fixed. You will probaby also want to do a Helpful DB commands is completely out of scope for this PR, which relates to the API documentation. I can add that later (maybe open an issue?) but I expect that particular section of the README to go away as the rest of the documentation is punched up. |
|
I saw that your can specify https://github.com/spacepy/dbprocessing/blob/master/unit_tests/test_DButils.py#L94-L95 https://github.com/spacepy/dbprocessing/blob/master/dbprocessing/Utils.py#L249 |
|
|
|
I did not realized that |
|
I really like the docs. Just going through... I a might be a little to thorough for this PR. 😄 |
Whoops, yep, that's confusing and deserved a comment at least, should have been in #95. I'll make a very small separate PR to clarify that. |
Maybe it's worth opening up an issue of just "pending docs updates" and throwing everything you find in there? I'll be doing a scrub shortly, so having a TODO list would definitely help. |
This is a substantial update to the docs handling to make sure the documentation is fully automatic: if new classes, methods, etc. are added all we need to do is add a docstring, not link it in anywhere by hand.
There are several changes here:
>>>in examplesThere should be no functionality change (except removing a class that was never used.) This looks like a much bigger deal than it really is.
PR Checklist
Closes #if this PR closes the issue, or some other reference, such asSee #if it is related in some other way)As there are no user-visible functionality changes, much of the above is irrelevant.
Documentation was tested to build on all minor versions of Sphinx from 1.3 through 4.2.