Bug #13418

Python SDK must have docstrings for all public interfaces

Added by Tom Morris 8 months ago. Updated 6 months ago.

Status:
New
Priority:
Normal
Assigned To:
-
Category:
-
Target version:
Start date:
Due date:
% Done:

0%

Estimated time:
Story points:
-

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

Related to Arvados - Feature #5214: [SDKs] Use sphinx to render for Python SDK docsNew

Related to Arvados - Feature #6865: [Documentation] Higher Level Python SDK Reference PageNew2015-08-03

History

#1 Updated by Peter Amstutz 7 months ago

  • Description updated (diff)

#2 Updated by Peter Amstutz 6 months ago

  • Related to Feature #5214: [SDKs] Use sphinx to render for Python SDK docs added

#3 Updated by Peter Amstutz 6 months ago

Currently leaning towards Doxygen as our alternative for documentation generation. It is very capable and customizable.

#4 Updated by Peter Amstutz 5 months ago

  • Related to Feature #6865: [Documentation] Higher Level Python SDK Reference Page added

Also available in: Atom PDF