What is the standard Python docstring format

Question

I have seen a few different styles of writing docstrings in Python  is there an official or  agreed-upon  style

User · Answer

I suggest using Vladimir Keleshev s pep257 Python program to check your docstrings against PEP-257 and the Numpy Docstring Standard for describing parameters  returns  etc   pep257 will report divergence you make from the standard and is called like pylint and pep8

User · Answer

It s Python  anything goes  Consider how to publish your documentation  Docstrings are invisible except to readers of your source code   People really like to browse and search documentation on the web  To achieve that  use the documentation tool Sphinx  It s the de-facto standard for documenting Python projects  The product is beautiful - take a look at https   python-guide readthedocs org en latest    The website Read the Docs will host your docs for free

User · Answer

Formats  Python docstrings can be written following several formats as the other posts showed  However the default Sphinx docstring format was not mentioned and is based on reStructuredText  reST   You can get some information about the main formats in this blog post   Note that the reST is recommended by the PEP 287  There follows the main used formats for docstrings   - Epytext  Historically a javadoc like style was prevalent  so it was taken as a base for Epydoc  with the called Epytext format  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       - reST  Nowadays  the probably more prevalent format is the reStructuredText  reST  format that is used by Sphinx to generate documentation  Note  it is used by default in JetBrains PyCharm  type triple quotes after defining a method and hit enter   It is also used by default as output format in Pyment   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  Google has their own format that is often used  It also can be interpreted by Sphinx  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  - Numpydoc  Note that Numpy recommend to follow their own numpydoc based on Google format and usable 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       Converting Generating  It is possible to use a tool like Pyment to automatically generate docstrings to a Python project not yet documented  or to convert existing docstrings  can be mixing several formats  from a format to an other one   Note  The examples are taken from the Pyment documentation

User · Answer

The Google style guide contains an excellent Python style guide  It includes conventions for readable docstring syntax that offers better guidance than PEP-257  For example  def square root n        quot  quot  quot 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        quot  quot  quot      pass  I like to extend this to also include type information in the arguments  as described in this Sphinx documentation tutorial  For example  def add value self  value        quot  quot  quot Add a new value          Args             value  str   the value to add       quot  quot  quot      pass

User · Answer

Docstring conventions are in PEP-257 with much more detail than PEP-8   However  docstrings seem to be far more personal than other areas of code  Different projects will have their own standard    I tend to always include docstrings  because they tend to demonstrate how to use the function and what it does very quickly    I prefer to keep things consistent  regardless of the length of the string  I like how to code looks when indentation and spacing are consistent  That means  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   And tend to leave off commenting on the first line in longer docstrings   def sq n               Return the square of n  accepting all numeric types        gt  gt  gt  sq 10      100       gt  gt  gt  sq 10 434      108 86835599999999      Raises a TypeError when input is invalid        gt  gt  gt  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

User · Answer

PEP-8 is the official python coding standard  It contains a section on docstrings  which refers to PEP-257 -- a complete specification for docstrings

User · Answer

As apparantly no one mentioned it  you can also use the Numpy Docstring Standard  It is widely used in the scientific community    The specification of the format from numpy together with an example You have a sphinx extension to render it  numpydoc And an example of how beautiful a rendered docstring can look like  http   docs scipy org doc numpy reference generated numpy mean html   The Napolean sphinx extension to parse Google-style docstrings  recommended in the answer of  Nathan  also supports Numpy-style docstring  and makes a short comparison of both   And last a basic example to give an idea how 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        gt  gt  gt  a  1 2 3       gt  gt  gt  print  x   3 for x in a       4  5  6              return True

[python] What is the standard Python docstring format?

Examples related to python

Examples related to coding-style

Examples related to documentation

Examples related to docstring