Style d'écriture de document de commentaires multilignes en Python

Qu'est-ce que la docstring

En génie logiciel, le codage joue en fait un très petit rôle, principalement d'autres choses, comme la rédaction de documents. Les documents sont des outils de communication.
En Python, il est fortement recommandé d'écrire des documents dans le code. Le code est le document le plus pratique, le plus facile à maintenir, le plus intuitif et le plus cohérent.
Le code est écrit et la documentation est sortie. En fait, Markdown a des idées similaires. Une fois le texte écrit, la composition est également terminée.
Regardez la définition de docstring dans PEP 0257 :

Une docstring est une chaîne littérale qui apparaît comme première instruction dans
une définition de module, de fonction, de classe ou de méthode <.>devient l'attribut spécial __doc__ de cet objet.
Pour faire simple, la première instruction qui apparaît dans un module, une fonction, une classe ou une méthode est la docstring. Il deviendra automatiquement l'attribut __doc__.

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

est accessible via foo.__doc__ pour obtenir « Ceci est la fonction foo ».

Divers styles de docstring :

Epytext

C'était autrefois un style populaire similaire à 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

C'est un style populaire maintenant, le style reST, le format royal du Sphinx. Personnellement, j’aime aussi utiliser ce style, qui est plus 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 (style Numpy)

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

outil docstring bibliothèque tierce pyment

Utilisé pour créer et convertir une docstring

La méthode d'utilisation consiste à utiliser pyment pour générer un patch, puis à appliquer le patch.

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

Détails : https://github.com/dadadel/pyment

Utilisez l'autodoc de sphinx pour produire automatiquement la documentation de l'API à partir de docstring , pas besoin de l'écrire à nouveau à la main

J'ai déjà écrit la docstring dans le code. Le contenu de l'écriture du document API est similaire à celui-ci. Dois-je d'abord le copier un par un ? Bien sûr que non. sphinx a une fonction autodoc.

Modifiez d'abord le fichier conf.py,
1 Il doit y avoir les extensions 'sphinx.ext.autodoc'
2 Assurez-vous que le module qui doit générer automatiquement la documentation peut être importé, c'est-à-dire. , c'est dans le chemin. Par exemple, vous aurez peut-être besoin de sys.path.insert(0, os.path.abspath('../..'))

Ensuite, écrivez le premier fichier,

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

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

Tapez la commande make html pour générer des documents pertinents à partir de la docstring sans avoir à écrire au préalable à la main

Voir l'effet :

<.>

Pour plus d'articles liés au style d'écriture de documents de commentaires multilignes en Python, veuillez faire attention au site Web PHP chinois !