Make documentation fully automatic

[jtniehof]

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:

• Remove patches for Sphinx 1.2 and set minimum Sphinx version to 1.3
• Set up Sphinx to automatically document all members of a module. This is a combination of template updates and a few patches to Sphinx for earlier versions. Current versions of Sphinx work without a patch, so these can be gradually phased out.
• Fix a deprecation warning for Sphinx 3 regarding the Javascript to hide the >>> in examples
• Make sure every object has at least a basic docstring, with a one-line summary, so it is properly picked up in documentation.

There 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

• [X] Pull request has descriptive title
• [X] Pull request gives overview of changes
• [X] New code has inline comments where necessary
• [X] (N/A) Any new modules, functions or classes have docstrings consistent with dbprocessing style
• [X] (N/A) Major new functionality has appropriate Sphinx documentation
• [X] (N/A) Added an entry to release notes if fixing a major bug or providing a major new feature
• [X] (N/A) New features and bug fixes should have unit tests
• [X] (N/A) Relevant issues are linked in the description (use Closes # if this PR closes the issue, or some other reference, such as See # 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.

[balarsen]

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.

def myCoolFun(in1: ClassOne, in2: int, in3: np.ndarray) -> bool:
    #code

[jtniehof]

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.

[dnadeau-lanl]

I keep getting this error when building the docs. Circle CI does not show anything.
I am going to ignore it.

/projects/sdndev/scripts/common/dbprocessing/build/lib/dbprocessing/__init__.py:docstring of dbprocessing:7: WARNING: autosummary: failed to import reports
WARNING: autodoc: failed to import class 'runObj' from module 'dbprocessing.runMe'; the following exception was raised:
Traceback (most recent call last):
  File "/projects/sdndev/anaconda3/envs/dbprocessingUNH3/lib/python3.9/site-packages/sphinx/util/inspect.py", line 439, in safe_getattr
    return getattr(obj, name, *defargs)
AttributeError: module 'dbprocessing.runMe' has no attribute 'runObj'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/projects/sdndev/anaconda3/envs/dbprocessingUNH3/lib/python3.9/site-packages/sphinx/ext/autodoc/importer.py", line 110, in import_object
    obj = attrgetter(obj, mangled_name)
  File "/projects/sdndev/anaconda3/envs/dbprocessingUNH3/lib/python3.9/site-packages/sphinx/ext/autodoc/__init__.py", line 332, in get_attr
    return autodoc_attrgetter(self.env.app, obj, name, *defargs)
  File "/projects/sdndev/anaconda3/envs/dbprocessingUNH3/lib/python3.9/site-packages/sphinx/ext/autodoc/__init__.py", line 2780, in autodoc_attrgetter
    return safe_getattr(obj, name, *defargs)
  File "/projects/sdndev/anaconda3/envs/dbprocessingUNH3/lib/python3.9/site-packages/sphinx/util/inspect.py", line 455, in safe_getattr
    raise AttributeError(name) from exc
AttributeError: runObj

<rst_epilog>:2: WARNING: Document or section may not begin with a transition.
/projects/sdndev/scripts/common/dbprocessing/docs/index.rst:19: WARNING: autosummary: failed to import dbprocessing.reports
looking for now-outdated files... none found

[jtniehof]

The reports import will fail if you don't have numpy or dateutil installed.

The "runObj" error suggests you didn't run python setup.py build before building the docs...it's finding an old version of runMe. runObj was removed in this PR.

"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 make clean before building the docs, after taking care of the above.

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.

[dnadeau-lanl]

I saw that your can specify 0 for ouput_product in PR #95. Can you update the doc?

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

[jtniehof]

I saw that your can specify 0 for ouput_product in PR #95. Can you update the doc?

1. This PR is unrelated to #95
2. The use of 0 for output_product isn't a behavior change. output_product can be any product_id. Whether that is a 0 or not depends on the autoincrement implementation of the DBMS. That test in #95 was to verify that the test for casting empty string to None did not destroy a 0 if that happened to be the ID of the output product. It's not clear if you're suggesting updating the docs on toNone (which isn't relevant, as 0 is not specially handled) or addProcess, where output_product is documented as the product ID, and an integer. That encompasses 0, and 0 isn't special.
3. The scope of this PR is getting the structure set up, not content update. (There are many many docstrings that are definitely wrong.)

[dnadeau-lanl]

make clean did the thing. I had left over .rst files in the autosummary directory.

[dnadeau-lanl]

I did not realized that 0 was an id in your test. The test says no_output, I thought 0 was testing a no_output ID.

[dnadeau-lanl]

I really like the docs. Just going through... I a might be a little to thorough for this PR. 😄

[jtniehof]

I did not realized that 0 was an id in your test. The test says no_output, I thought 0 was testing a no_output ID.

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.

[jtniehof]

I really like the docs. Just going through... I a might be a little to thorough for this PR. smile

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.