Compiling style of multi-line comment documents in Python

It is very convenient to compile small program documents with multi-line annotations in Python, and there are also a variety of conventional formats, here we will summarize the writing style of the multi-line annotation document in the most common Python: What is docstring

In software engineering, coding is very small, most of which are other things, such as writing documents. Documentation is a tool for communication.
In Python, it is highly recommended that you write documents in the code. the code is a document, which is convenient, easy to maintain, intuitive, and consistent.
After the code is written, the document is displayed. In fact, Markdown is similar to this idea. after the text is written, the layout is complete.
Let's take a 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.
Simply put, the first statement that appears in the module, function, class, and method is docstring. Will automatically become the property _ doc __.

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

You can access 'this is function Foo' through foo. _ doc '.

Various docstring styles:

Epytext

This is a popular style that has always been 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 now a popular style, reST style, and the Royal format of Sphinx. I personally like this style and it is relatively 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 paramReturns:  This is a description of what is returnedRaises:  KeyError - raises an exception"""

Numpydoc (Numpy style)

"""My numpydoc description of a kindof very exhautive numpydoc format docstring.Parameters----------first : array_like  the 1st param name `first`second :  the 2nd paramthird : {'value', 'other'}, optional  the 3rd param, by default 'value'Returns-------string  a value in a stringRaises------KeyError  when a key errorOtherError  when an other error"""

Docstring tool-third-party library pyment

Use to create and convert docstring.
You can use pyment to generate a patch and then create a patch.

$ Pyment test. py # generate patch $ patch-p1 <test. py. patch # patch

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

Use the autodoc of sphinx to automatically produce api documents from docstring without writing them again.

I have already written docstring in the code. the content of the api documentation is similar to this. Do I need to copy the past rst one by one? Of course not. Sphinx has the autodoc function.
First, edit the conf. py file,
1. you must have the extensions 'sphextension. ext. autodoc '.
2. make sure that the module that requires automatic document generation can be imported, that is, in the path. For example, sys. path. insert (0, OS. path. abspath ('.../..') may be required ('../..'))

Then, write the rst file,

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

After you press the make html command, you can generate relevant documents from docstring. you do not need to write the documents again.
View results:

For more articles about the writing style of multi-line annotation documents in Python, please follow the PHP Chinese network!