Docstrings¶
Mit der Sphinx-Erweiterung sphinx.ext.autodoc können Docstrings auch in die Dokumentation aufgenommen werden. Die folgenden Direktiven können angegeben werden
… für Klassen und Ausnahmen:
… für funktionsähnliche Objekte:
… für Daten und Attribute:
Installation¶
sphinx.ext.autodoc ist normalerweise bereits in der
Sphinx-Konfigurationsdatei docs/conf.py angegeben:
extensions = ["sphinx.ext.autodoc", ...]
Wenn euer Paket und die zugehörige Dokumentation Teil desselben Repository
sind, werden sie immer dieselbe relative Position im Dateisystem haben. In
diesem Fall könnt ihr einfach die Sphinx-Konfiguration für sys.path
bearbeiten, um den relativen Pfad zum Paket anzugeben, also:
sys.path.insert(0, os.path.abspath(".."))
import MODULE
Wenn ihr eure Sphinx-Dokumentation in einer virtuellen Umgebung installiert
habt, könnt ihr euer Paket auch dort mitinstallieren, z.B. indem ihr es in eure requirements.txt-Datei eintragt.
Beispiele¶
Hier findet ihr einige Beispiele aus der Dokumentation des
Python-string-Moduls:
``autodoc``-Beispiele
=====================
``string``-Modul
----------------
.. automodule:: string
``string.Template``-Klasse
--------------------------
.. autoclass:: Template
``string.capwords``-Funktion
----------------------------
.. autofunction:: capwords
Die Ausgabe ist autodoc-Beispiele.
Richtlinien¶
In PEP 8 gibt es nur einen kurzen Hinweise auf Konventionen für einen guten Docstring: Documentation Strings. Weitere PEPs beziehen sich auf das Docstring Processing System Framework:
- PEP 257
beschreibt Docstring-Konventionen:
Was sollte wo dokumentiert werden?
Die erste Zeile soll eine einzeilige Zusammenfassung sein.
- PEP 258
spezifiziert die System zur Verarbeitung von Docstrings.
- PEP 287
spezifiziert die Docstring-Syntax.
Im Google Python Style Guide gibt es darüberhinaus noch spezifischere Richtlinien für Python Konnentare und Docstrings. Auch der NumPy Style guide liefert noch weitere Docstring-Standards. Der wesentliche Unterschied zwischen beiden besteht darin, dass Google Einrückungen verwendet und NumPy Unterstreichungen:
- Google Python Style Guide:
def func(arg1: int, arg2: str) -> bool: """Summary line. Extended description of function. Args: arg1 (int): Description of arg1 arg2 (str): Description of arg2 Returns: bool: Description of return value """ return True
- NumPy Style Guide:
def func(arg1: int, arg2: str) -> bool: """Summary line. Extended description of function. Parameters ---------- arg1 : int Description of arg1 arg2 : str Description of arg2 Returns ------- bool Description of return value """ return True
sphinx.ext.napoleon¶
Die Sphinx-Erweiterung sphinx.ext.napoleon verarbeitet sowohl Docstrings, die dem Google Python Style Guide als auch dem NumPy Style Guide entsprechen:
Detaillierte Konfigurationsoptionen findet ihr in sphinxcontrib.napoleon.Config.
sphinx-autodoc-typehints¶
Mit PEP 484 wurde eine Standardmethode für den Ausdruck von Typen in Python-Code eingeführt. Damit können Typen auch in Docstrings unterschiedlich ausgedrückt werden. Die Variante mit Typen nach PEP 484 hat den Vorteil, dass Typ-Tester und IDEs zur statischen Codeanalyse eingesetzt werden können.
- Python 3 Type-Annotations in Docstrings:
def func(arg1: int, arg2: str) -> bool: """Summary line. Extended description of function. Args: arg1 (int): Description of arg1 arg2 (str): Description of arg2 Returns: bool: Description of return value """ return True