Docstring documentation content

[coding-to-music]

https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings

[coding-to-music]

https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard

"""This is the form of a docstring.

It can be spread over several lines.

"""

[coding-to-music]

Docstring Standard A documentation string (docstring) is a string that describes a module, function, class, or method definition. The docstring is a special attribute of the object (object.doc) and, for consistency, is surrounded by triple double quotes, i.e.:

"""This is the form of a docstring.

It can be spread over several lines.

""" NumPy, SciPy, and the scikits follow a common convention for docstrings that provides for consistency, while also allowing our toolchain to produce well-formatted reference guides. This document describes the current community consensus for such a standard. If you have suggestions for improvements, post them on the numpy-discussion list.

Our docstring standard uses re-structured text (reST) syntax and is rendered using Sphinx (a pre-processor that understands the particular documentation style we are using). While a rich set of markup is available, we limit ourselves to a very basic subset, in order to provide docstrings that are easy to read on text-only terminals.

A guiding principle is that human readers of the text are given precedence over contorting docstrings so our tools produce nice output. Rather than sacrificing the readability of the docstrings, we have written pre-processors to assist Sphinx in its task.

The length of docstring lines should be kept to 75 characters to facilitate reading the docstrings in text terminals.

[coding-to-music]

https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html

sphinx.ext.autodoc – Include documentation from docstrings¶ This extension can import the modules you are documenting, and pull in documentation from docstrings in a semi-automatic way.

Note

For Sphinx (actually, the Python interpreter that executes Sphinx) to find your module, it must be importable. That means that the module or the package must be in one of the directories on sys.path – adapt your sys.path in the configuration file accordingly.

Warning

autodoc imports the modules to be documented. If any modules have side effects on import, these will be executed by autodoc when sphinx-build is run.

If you document scripts (as opposed to library modules), make sure their main routine is protected by a if name == 'main' condition.

For this to work, the docstrings must of course be written in correct reStructuredText. You can then use all of the usual Sphinx markup in the docstrings, and it will end up correctly in the documentation. Together with hand-written documentation, this technique eases the pain of having to maintain two locations for documentation, while at the same time avoiding auto-generated-looking pure API documentation.

If you prefer NumPy or Google style docstrings over reStructuredText, you can also enable the napoleon extension. napoleon is a preprocessor that converts your docstrings to correct reStructuredText before autodoc processes them.