Support #13418
Updated by Peter Amstutz almost 6 years ago
Per "PEP-8":https://www.python.org/dev/peps/pep-0008/#documentation-strings, as referenced in our "coding standards":https://dev.arvados.org/projects/arvados/wiki/Coding_Standards#Python, we should "Write docstrings for all public modules, functions, classes, and methods."
Although this should already be covered as part of our peer review process, perhaps we should also consider using a static checker as part of the CI build process to automate detection of oversights.
We should do a full review of the Python SDK documentation as presented on doc.arvados.org.
A few other problems: epydoc (which we currently use, produces javadoc-like documentation pages) is poor for both learning and reference. Also, existing documentation strings are formatted inconsistently (for example, using ReStructured text, which isn't supported by epydoc).
Dynamically generated methods (everything produced by the discovery document) are not included in the Python SDK documentation. We should figure out a way to ensure that they are included.
Proposed solutions:
* Review presentation of API on doc.arvados.org and fill in gaps in docstrings needed for learning and reference
* Generate method stubs (with documentation) from the discovery document so they get included in online documentation
* Dump epydoc and use another documentation generator, such as sphinx.
* Add a Python code linter to run-tests, such as flake8, to check for missing documentation bad formatting. (Consider using 'tox' to orchestrate testing and checking.) Also consider adding type annotations and checking with mypy.