Closed jtniehof closed 2 years ago
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
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.
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
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.
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
I saw that your can specify
0
for ouput_product in PR #95. Can you update the doc?
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.make clean did the thing. I had left over .rst files in the autosummary directory.
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.
I really like the docs. Just going through... I a might be a little to thorough for this PR. 😄
I did not realized that
0
was an id in your test. The test saysno_output
, I thought0
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.
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.
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.