Docstrings

Description

• overview different docstring methods: What is the standard Python docstring format?

Links

• PEP 8: https://www.python.org/dev/peps/pep-0008/

• PEP 257: https://www.python.org/dev/peps/pep-0257/

• PEP 287 - reStructuredText Docstring Format: https://www.python.org/dev/peps/pep-0287/

• Google Python Style Guide: google/styleguide

• Example Google Style Python Docstrings: https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html

Napoleon and Sphinx

Cross-referencing Python objects

• function: :func:`module_name.function_name`

• class: :class:`module_name.ClassName`

• meth: :meth:`module_name.ClassName.method_name`

• prefix ~: link text will only be the last component of the target

• also see: Cross-referencing syntax

• also see: Cross-referencing Python objects

Docstring Sections

The most comment docstring sections are:

• Args:

• Returns:

• Raises:

• Yields:

• See Also:

• also see: Docstring Sections