Multi-line comment document writing style in Python

What is docstring

In software engineering, coding actually plays a very small part, mostly other things, such as writing documents. Documents are tools for communication.
In Python, it is highly recommended to write documents in the code. The code is the document, which is more convenient, easy to maintain, intuitive and consistent.
After the code is written, the documentation is also out. In fact, Markdown has similar ideas. After the text is written, the typesetting is also completed.
Look at the definition of docstring in PEP 0257:

A docstring is a string literal that occurs as the first statement in
a module, function, class, or method definition. Such a docstring
becomes the __doc__ special attribute of that object.
To put it simply, the first statement that appears in a module, function, class, or method is the docstring. It will automatically become the attribute __doc__.

def foo():
  """ This is function foo"""

Can be accessed through foo.__doc__ to get 'This is function foo'.

Various docstring styles:

Epytext

This was once a popular style similar to javadoc.

"""
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

This is a popular style now, reST style, the royal format of Sphinx. I personally also like to use this style, which is more compact.

"""
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 Style

"""
This is a groups style docs.

Parameters:
  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
"""

Numpydoc (Numpy style)

"""
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
"""

docstring tool third-party library pyment

is used to create and convert docstring.
The method of use is to use pyment to generate a patch and then apply the patch.

$ pyment test.py      #生成patch
$ patch -p1 < test.py.patch #打patch

Details: https://github.com/dadadel/pyment

Use sphinx's autodoc to automatically produce api documents from docstring, no need Write it again by hand

I have already written the docstring in the code. The content of writing the API document is similar to this. Do I need to copy it one by one to rst? Of course not. sphinx has autodoc function.
First edit the conf.py file,
1. There must be the 'sphinx.ext.autodoc' extensions
2. Make sure that the module that needs to automatically generate documentation can be imported, that is, it is in the path. For example, you may need sys.path.insert(0, os.path.abspath('../..'))

Then, write the rst file,

xxx_api module
---------------------

.. automodule:: xxx_api
  :members:
  :undoc-members:
  :show-inheritance:

Type the make html command to generate relevant documents from the docstring without having to write rst by hand.
See the effect:

For more articles related to the multi-line comment document writing style in Python, please pay attention to the PHP Chinese website!