Schreibstil für mehrzeilige Kommentardokumente in Python

Was ist Docstring?

In der Softwareentwicklung spielt das Codieren tatsächlich eine sehr kleine Rolle, hauptsächlich andere Dinge, wie zum Beispiel das Schreiben von Dokumenten. Dokumente sind Werkzeuge der Kommunikation.
In Python wird dringend empfohlen, Dokumente im Code zu schreiben, was bequemer, einfacher zu warten, intuitiver und konsistenter ist.
Der Code ist geschrieben und die Dokumentation ist verfügbar. Tatsächlich hat Markdown ähnliche Ideen. Nachdem der Text geschrieben wurde, ist auch der Satz abgeschlossen.
Sehen Sie sich die Definition von Docstring in PEP 0257 an:

Ein Docstring ist ein String-Literal, das als erste Anweisung in
einer Modul-, Funktions-, Klassen- oder Methodendefinition wird zum speziellen __doc__-Attribut dieses Objekts.
Einfach ausgedrückt ist die erste Anweisung, die in einem Modul, einer Funktion, einer Klasse oder einer Methode erscheint, der Docstring. Es wird automatisch zum Attribut __doc__.

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

kann über foo.__doc__ aufgerufen werden, um „Dies ist Funktion foo“ zu erhalten.

Verschiedene Dokumentzeichenfolgenstile:

Epytext

Dies war einst ein beliebter Stil, ähnlich wie 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

Dies ist jetzt ein beliebter Stil, reST-Stil, das königliche Format von Sphinx. Ich persönlich verwende auch gerne diesen Stil, der kompakter ist.

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

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

"""
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, Bibliothek von Drittanbietern, Pyment

Wird zum Erstellen und Konvertieren von Dokumentzeichenfolgen verwendet.

Die Verwendungsmethode besteht darin, mit pyment einen Patch zu generieren und den Patch dann anzuwenden.

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

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

Verwenden Sie Sphinx's Autodoc, um automatisch API-Dokumentation aus Docstring zu erstellen , es ist nicht nötig, es noch einmal von Hand zu schreiben

Ich habe die Dokumentzeichenfolge bereits in den Code geschrieben. Der Inhalt des API-Dokuments ist ähnlich wie folgt: Muss ich es zuerst einzeln kopieren? Natürlich nicht. Sphinx verfügt über eine Autodoc-Funktion.

Bearbeiten Sie zuerst die Datei conf.py,
1. Es müssen die Erweiterungen „sphinx.ext.autodoc“ vorhanden sein.
2 Stellen Sie sicher, dass das Modul, das die Dokumentation automatisch generieren muss, importiert werden kann , es ist im Weg. Beispielsweise benötigen Sie möglicherweise sys.path.insert(0, os.path.abspath('../..'))

. Schreiben Sie dann die erste Datei,

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

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

Geben Sie den Befehl „make html“ ein, um relevante Dokumente aus dem Dokumentstring zu generieren, ohne zuerst von Hand schreiben zu müssen:

Weitere Artikel zum mehrzeiligen Kommentardokument-Schreibstil in Python finden Sie auf der chinesischen PHP-Website!