[Python] Docstring

Docstring is a powerful tool to document in Python.

Docstring becomes a __doc__ property for the object.

You can find the official Docstring Conventions in the below link.

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

Docstring Syntax

Python recommends using """triple double quotes""" for Docstring.

You can start with r for raw string and u for Unicode string.

Docstring Specification

One-line Docstrings

• Triple quotes are used even though the string fits on one line. This makes it easy to later expand it.
• The closing quotes are on the same line as the opening quotes.
• There's no blank line either before or after the docstring.
• The docstring is a phrase ending in a period. It prescribes the function or method's effect as a command, not as a description.
• The one-line docstring should NOT be a "signature" reiterating the function/method parameters (which can be obtained by introspection).

Multi-line Docstrings

• Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description.
• Insert a blank line after all docstrings (one-line or multi-line) that document a class.
• The docstring of a script (a stand-alone program) should be usable as its "usage" message, printed when the script is invoked with incorrect or missing arguments (or perhaps with a "-h" option, for "help").
• The docstring for a module should generally list the classes, exceptions, and functions (and any other objects) that are exported by the module, with a one-line summary of each.
• The docstring for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable). Optional arguments should be indicated. It should be documented whether keyword arguments are part of the interface.
• The docstring for a class should summarize its behavior and list the public methods and instance variables.

Docstring Styles

These are mostly used Docstring styles.

Google

https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings

PEP-287: reStructuredText Docstring Format

https://www.python.org/dev/peps/pep-0287/

Numpy/Scipy

https://numpydoc.readthedocs.io/en/latest/format.html

Epytext

http://epydoc.sourceforge.net/manual-epytext.html

Docstring Tools

Sphinx

This is the most popular docstring tool.

You can get this tool at the below link.

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

$ pip install -U sphinx

You can find the document to use sphinx.

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

Read the Docs

https://readthedocs.org/

Pycco

https://pycco-docs.github.io/pycco/

Epydocs

http://epydoc.sourceforge.net/

Docstring Usage

Let's use the Sphinx.

$ sphinx-quickstart

And input the information as following the terminal.

Then, it will be set up.

Now, build the docstring with Sphinx.

$ sphinx-build <SOURCE_PATH> <OUTPUT_PATH>

You can create an HTML page with a docstring.

$ make html

Docstring Example

Please look at the example style of Google.

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