Multi-line comment document writing style in Python-Python Tutorial-php.cn

Multi-line comment document writing style in Python

高洛峰

Release： 2017-03-02 11:20:09

Original

1714 people have browsed it

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__.

1 2	`def` `foo():` `""" This is function foo"""`

Copy after login

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

Copy after login

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

Copy after login

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

Copy after login

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 : {&#39;value&#39;, &#39;other&#39;}, optional
  the 3rd param, by default &#39;value&#39;
 
Returns
-------
string
  a value in a string
 
Raises
------
KeyError
  when a key error
OtherError
  when an other error
"""

Copy after login

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.

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

Copy after login

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:

Copy after login

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

Multi-line comment document writing style in Python

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