Generate complete API docs using sphinx-apidoc #1330
Conversation
1135 warnings
For reference, here is the regex I used: ``` cd source for f in */dev.rst; do gsed -i -r -e 's/(\s+)(:members:)/\1\2\n\1:noindex:/g' $f done ``` Note: gsed should be gnu sed (I used v4.4) which supports the -r option (the sed shipped with recent MacOS versions won't do) Down to 263 warnings.
Now down to 80 warnings that actually need to be looked into
down to 48 warnings
down to 42 warnings
Only 3 warnings remain, two related to a broken import and one because of an internal guard
Added running of sphinx-apidoc to Makefile. Running apidoc.sh is equivalent to running make clean make all The default target now makes both apidoc and html, i.e. the travis scripts don't need to be changed.
make default target instead of html (html does not build the apidoc automatically)
Unfortunately, sphinx-apidoc currently does not allow to adjust the tocdepth of the subpackage tocs (sphinx-doc/sphinx#2108)
It was not being used and it had import errors
This file became obsolete when a general test loading system was implemented way back for both backends
…compile the documentation - they don't make sense such checks anyway during the documentation compilation
QueryTool was deprecated in v0.8.0 (and was being imported also in sqlalchemy, where it didn't exist)
|
Copied from old PR: What remains is to decide what to do with the old, manually generated API documentation. Delete:
Others contain either a bit of text as well or some ordered selection, which might contain some thought. In my view, these could be integrated in other parts of the documentation, if needed. To Decide:
@giovannipizzi Do you agree with this assessment? |
still remaining: sphinx does not want to make references to protected methods (starting with _ and __)
issue with private methods not being referenced was actually a sphinx bug sphinx-doc/sphinx#4091 Fixed in sphinx 1.6.6 Lots of nice new errors popping up :-)
sphinx-apidoc did not include private/special members. back to 106 warnings ;-)
|
@sphuber One of the documentation errors pointed to what seems like a duplicate function (quite a few lines) https://github.com/aiidateam/aiida_core/blob/82b4562579661098cbd2ae285f8743c3d02bb10a/aiida/common/deserialization.py#L19 Can one of these be eliminated? |
plus a few nitpicky warnings still to fix (total: 28)
2 nitpicky warnings remaining (will go away, when code duplication is removed) 1 actual warning that I'm unable to figure out
this removes just documents that were incomplete lists of the classes. next: try to merge docs that contain some more information
it's still far from ideal... too many "Subpackages" / "Submodules". We could use something like this: https://github.com/goerz/better-apidoc but perhaps we just wait until sphinx-apidoc finally gets a bit more configurable.
also move resultmanager docs to working_with_aiida
|
@sphuber @giovannipizzi The apidoc is not yet entirely ideal in the sense that it's a little bit bloated by the page of every package first containing the "Package" and "Subpackage" modules.
Or we keep it as it is for the moment and make it better, once sphinx-apidoc makes it easy to do. |
ltalirz
changed the title
Fix #1255
sphinx-apidocQueryTool(deprecated in v0.8.0, import was anyhow broken)This is a continuation of PR #1255
Let's see whether we can get this into aiida-core v0.11.3