Docstring style¶
Public API docstrings are rendered by mkdocstrings. Types come from annotations (annotations_path: brief in mkdocs.yml), not from repeated (int, optional) lines in Args.
Summary line¶
One sentence describing what the callable does. Use imperative or “Return …” consistently within a module.
Args¶
Args:
checkpoint_dir: Latest checkpoint directory, or ``None`` when there is none.
- No parameter types in the docstring.
- Defaults are optional when obvious from the signature.
Returns¶
Use a short prose paragraph when the return value needs explanation. Omit the entire Returns: section when the annotation is -> None and adds nothing.
Raises¶
Raises:
ValueError: When ``reporter`` is not a known backend name.
Cross-references¶
Sphinx-style markup works in API pages: :func:`run_experiment`, mlflow.
Long constructors¶
Classes such as TrainingConfig document behavior in Training loop instead of listing every field in __init__.
IDE template¶
Project root .mustache is wired in .vscode/settings.json for the autoDocstring extension.
To bulk-fix legacy Args type lines in existing docstrings:
python3 scripts/normalize_docstrings.py
Canonical examples: mlkit.util.report.run_file, mlkit.util.failure, mlkit.util.experiment.runner.
Example entry scripts (example/**/main*.py, example/**/infer*.py) place the module docstring first, then sys.path setup, then remaining imports (Ruff E402).