Elegant Python-code as document DocString

What is DocString

In software engineering, in fact, the part of the code is very small, mostly other things, such as writing documents. Documentation is a tool for communication.
In Python, the comparison is respected in the code to write documents, code is the document, more convenient, easy to maintain, intuitive, consistent.
After the code is written, the document is out. In fact, Markdown is similar to this idea, the text is finished, typesetting has been completed.
Look at the definition of docstring in pep 0257:

A docstring is a string literal this 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 modules, functions, classes, methods, is docstring. Automatically becomes the attribute __doc__.

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

The ' This is function foo ' can be accessed via foo.__doc__.

All kinds of docstring style Epytext

This has been a popular style that has 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 popular in a style, restful style, Sphinx's queen format. I personally also like to use this style, 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"""

Third-party library of docstring tools pyment

Used to create and convert docstring.
The way to use this is to generate a patch with pyment and then patch.

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

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

Use Sphinx's Autodoc to automate the production of API documents from DocString without having to write them again

I have written docstring in the code, the content of the API document is similar to this, do you want a copy of the past RST? Of course not. Sphinx has autodoc function.
first edit the conf.py file ,
1. To have ' sphinx.ext.autodoc ' this extensions
2. Ensure that the module that needs to automatically generate the document can be import, that 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:

With the make HTML command, you can generate related documents from docstring without having to write the RST again.
Look at the effect:

Copyright NOTICE: This article for Bo Master original article, without Bo Master permission not reproduced.

Elegant Python-code as document DocString