Sphinx¶

Sphinx is far and away the most popular Python documentationtool.Use it. It convertsreStructuredText markup languageinto a range of output formats including HTML, LaTeX (for printablePDF versions), manual pages, and plain text.

There is alsogreat,free hosting for yourSphinx docs:Read The Docs. Use it. You can configure it with commit hooks toyour source repository so that rebuilding your documentation willhappen automatically.

When run,Sphinx will import your code and using Python’s introspectionfeatures it will extract all function, method, and class signatures. It willalso extract the accompanying docstrings, and compile it all into wellstructured and easily readable documentation for your project.

reStructuredText¶

Most Python documentation is written withreStructuredText. It’s likeMarkdown, but with all the optional extensions built in.

ThereStructuredText Primer and thereStructuredText QuickReference should help you familiarize yourself with its syntax.

Commenting Sections of Code¶

Do not use triple-quote strings to comment code. This is not a goodpractice, because line-oriented command-line tools such as grep willnot be aware that the commented code is inactive. It is better to addhashes at the proper indentation level for every commented line. Youreditor probably has the ability to do this easily, and it is worthlearning the comment/uncomment toggle.

Docstrings and Magic¶

Some tools use docstrings to embed more-than-documentation behavior,such as unit test logic. Those can be nice, but you won’t ever gowrong with vanilla “here’s what this does.”

Tools likeSphinx will parse your docstrings as reStructuredText and render itcorrectly as HTML. This makes it very easy to embed snippets of example code ina project’s documentation.

Additionally,Doctest will read all embedded docstrings that look like inputfrom the Python commandline (prefixed with “>>>”) and run them, checking to seeif the output of the command matches the text on the following line. Thisallows developers to embed real examples and usage of functions alongsidetheir source code. As a side effect, it also ensures that their code istested and works.

defmy_function(a,b):"""    >>> my_function(2, 3)    6    >>> my_function('a', 3)    'aaa'    """returna*b

Docstrings versus Block comments¶

These aren’t interchangeable. For a function or class, the leadingcomment block is a programmer’s note. The docstring describes theoperation of the function or class:

# This function slows down program execution for some reason.defsquare_and_rooter(x):"""Returns the square root of self times self."""...

Unlike block comments, docstrings are built into the Python language itself.This means you can use all of Python’s powerful introspection capabilities toaccess docstrings at runtime, compared with comments which are optimized out.Docstrings are accessible from both the__doc__ dunder attribute for almostevery Python object, as well as with the built inhelp() function.

While block comments are usually used to explainwhat a section of code isdoing, or the specifics of an algorithm, docstrings are more intended towardsexplaining other users of your code (or you in 6 months time)how aparticular function can be used and the general purpose of a function, class,or module.

Writing Docstrings¶

Depending on the complexity of the function, method, or class being written, aone-line docstring may be perfectly appropriate. These are generally used forreally obvious cases, such as:

defadd(a,b):"""Add two numbers and return the result."""returna+b

The docstring should describe the function in a way that is easy to understand.For simple cases like trivial functions and classes, simply embedding thefunction’s signature (i.e.add(a, b) -> result) in the docstring isunnecessary. This is because with Python’sinspect module, it is alreadyquite easy to find this information if needed, and it is also readily availableby reading the source code.

In larger or more complex projects however, it is often a good idea to givemore information about a function, what it does, any exceptions it may raise,what it returns, or relevant details about the parameters.

For more detailed documentation of code a popular style used, is the one used by theNumPy project, often calledNumPy style docstrings. While it can take up morelines than the previous example, it allows the developer to include a lotmore information about a method, function, or class.

defrandom_number_generator(arg1,arg2):"""    Summary line.    Extended description of function.    Parameters    ----------    arg1 : int        Description of arg1    arg2 : str        Description of arg2    Returns    -------    int        Description of return value    """return42

Thesphinx.ext.napoleon plugin allows Sphinx to parse this style ofdocstrings, making it easy to incorporate NumPy style docstrings into yourproject.

At the end of the day, it doesn’t really matter what style is used for writingdocstrings; their purpose is to serve as documentation for anyone who may needto read or make changes to your code. As long as it is correct, understandable,and gets the relevant points across then it has done the job it was designed todo.

For further reading on docstrings, feel free to consultPEP 257