Coder Perfect

What are the most prevalent docstring formats in Python? [closed]


What are the most prevalent styles of writing docstrings in Python? I’ve seen a few different styles of writing docstrings in Python.

Asked by Noah McIlraith

Solution #1

As the previous entries demonstrated, Python docstrings may be written in a variety of formats. However, the default Sphinx docstring format, which is based on reStructuredText, was not stated (reST). This blog post contains some information on the most common formats.

Note that the PEP 287 recommends the reST.

The most commonly used docstring formats are shown below.

Because a javadoc-like style was popular in the past, Epydoc (which uses the Epytext format) was used to generate documentation.


This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception

The reStructuredText (reST) format, which is used by Sphinx to generate documentation, is arguably the more used format nowadays. It’s worth noting that JetBrains PyCharm uses it by default (type triple quotes after defining a method and hit enter). Pyment also uses it as the default output format.


This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception

Google has its own format, which is widely used. Sphinx can decipher it as well (ie. using Napoleon plugin).


This is an example of Google style.

    param1: This is the first param.
    param2: This is a second param.

    This is a description of what is returned.

    KeyError: Raises an exception.

Even more examples

Numpy recommends using their own numpydoc, which is based on Google format and can be read by Sphinx.

My numpydoc description of a kind
of very exhautive numpydoc format docstring.

first : array_like
    the 1st param name `first`
second :
    the 2nd param
third : {'value', 'other'}, optional
    the 3rd param, by default 'value'

    a value in a string

    when a key error
    when an other error

It’s possible to use a tool like Pyment to generate docstrings for a Python project that hasn’t been documented yet, or to convert existing docstrings (which may contain many forms) to a new format.

The following examples are from the Pyment manual.

Answered by daouzli

Solution #2

A great Python style guide can be found in the Google style guide. It includes docstring syntax conventions that are more user-friendly than PEP-257. Consider the following scenario:

def square_root(n):
    """Calculate the square root of a number.

        n: the number to get the square root of.
        the square root of n.
        TypeError: if n is not a number.
        ValueError: if n is negative.


As mentioned in this Sphinx documentation tutorial, I wish to enhance this to add type information in the arguments. Consider the following scenario:

def add_value(self, value):
    """Add a new value.

           value (str): the value to add.

Answered by Nathan

Solution #3

PEP-257 has substantially more information about docstring conventions than PEP-8.

Docstrings, on the other hand, appear to be significantly more personal than other regions of code. Each project will have its own set of standards.

I usually add docstrings in my code since they rapidly demonstrate how to use the function and what it accomplishes.

Regardless of the length of the string, I want to keep things consistent. When indentation and space are constant, I appreciate how the code looks. That is to say, I use:

def sq(n):
    Return the square of n. 
    return n * n


def sq(n):
    """Returns the square of n."""
    return n * n

In lengthier docstrings, I like to skip commenting on the first line:

def sq(n):
    Return the square of n, accepting all numeric types:

    >>> sq(10)

    >>> sq(10.434)

    Raises a TypeError when input is invalid:

    >>> sq(4*'435')
    Traceback (most recent call last):
    TypeError: can't multiply sequence by non-int of type 'str'

    return n*n

Meaning I find docstrings that start like this to be messy.

def sq(n):
    """Return the squared result. 

Answered by Tim McNamara

Solution #4

You can also use the Numpy Docstring Standard, which no one seems to have mentioned. In the scientific world, it is commonly utilized.

The Napolean sphinx plugin for parsing Google-style docstrings (suggested in @Nathan’s answer) also supports Numpy-style docstrings, and compares the two.

Finally, here’s a simple example to give you an idea of what it looks like:

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

        Description of return value

    See Also
    otherfunc : some related other function

    These are written in doctest format, and should illustrate how to
    use the function.

    >>> a=[1,2,3]
    >>> print [x + 3 for x in a]
    [4, 5, 6]
    return True

Answered by joris

Solution #5

It’s Python, so you can do whatever you want. Consider how you’ll get your documentation out there. Except for readers of your source code, docstrings are invisible.

People enjoy browsing and searching for documentation on the internet. Use Sphinx, a documentation tool, to accomplish this. It’s the de-facto standard for Python project documentation. Take a peek at to see the finished work. Your documents will be hosted for free on the website Read the Docs.

Answered by Colonel Panic

Post is based on