Problem
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.
Example:
"""
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.
Example:
"""
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).
Example:
"""
This is an example of Google style.
Args:
param1: This is the first param.
param2: This is a second param.
Returns:
This is a description of what is returned.
Raises:
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.
Parameters
----------
first : array_like
the 1st param name `first`
second :
the 2nd param
third : {'value', 'other'}, optional
the 3rd param, by default 'value'
Returns
-------
string
a value in a string
Raises
------
KeyError
when a key error
OtherError
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.
Args:
n: the number to get the square root of.
Returns:
the square root of n.
Raises:
TypeError: if n is not a number.
ValueError: if n is negative.
"""
pass
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.
Args:
value (str): the value to add.
"""
pass
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 tend to always include docstrings, because they tend to demonstrate how to use the function and what it does very quickly.
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
Over:
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)
100
>>> sq(10.434)
108.86835599999999
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
In other words, I find docstrings that begin like this to be unwieldy.
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.
Parameters
----------
arg1 : int
Description of arg1
arg2 : str
Description of arg2
Returns
-------
bool
Description of return value
See Also
--------
otherfunc : some related other function
Examples
--------
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 https://python-guide.readthedocs.org/en/latest/ 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 https://stackoverflow.com/questions/3898572/what-are-the-most-common-python-docstring-formats