Bug #13418
Python SDK must have docstrings for all public interfaces
0%
Description
Per PEP-8, as referenced in our coding standards, 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.
Related issues
History
#1
Updated by Peter Amstutz over 2 years ago
- Description updated (diff)
#2
Updated by Peter Amstutz over 2 years ago
- Related to Feature #5214: [SDKs] Use sphinx to render for Python SDK docs added
#3
Updated by Peter Amstutz over 2 years ago
Currently leaning towards Doxygen as our alternative for documentation generation. It is very capable and customizable.
#4
Updated by Peter Amstutz over 2 years ago
- Related to Feature #6865: [Documentation] Higher Level Python SDK Reference Page added
#5
Updated by Tom Morris almost 2 years ago
- Related to Story #15015: replace epydoc added