Docstrings#
Mit der Sphinx-Erweiterung sphinx.ext.autodoc können Docstrings auch in die Dokumentation aufgenommen werden. Die folgenden drei Direktiven können angegeben werden:
Diese dokumentieren ein Modul, eine Klasse oder eine Ausnahme unter Verwendung des docstring des jeweiligen Objekts.
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 Repositorys
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 requests
Wenn ihr eure Sphinx-Dokumentation in einer virtuellen Umgebung installiert habt, könnt ihr euer Paket auch dort mitinstallieren:
$ python -m pip install my.package
oder, wenn ihr das Paket weiterentwickeln wollt, mit:
$ python -m pip install -e https://github.com/veit/my.package.git
Beispiele#
Hier findet ihr einige Beispiele aus der API-Dokumentation für das requests-Modul:
Docstrings-Beispiel
===================
.. module:: requests
Main Interface
--------------
.. autofunction:: head
Exceptions
----------
.. autoexception:: requests.RequestException
Request Sessions
----------------
.. autoclass:: Session
:inherited-members:
Dies führt zum Docstrings-Beispiel, die aus den folgenden Docstrings generiert wird:
Bemerkung
Ihr solltet diese Richtlinien befolgen, wenn ihr Docstrings schreibt:
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 Typtester und IDEs zur statischen Codeanalyse eingesetzt werden können.
Python 3 Type-Annotations:
def func(arg1: int, arg2: str) -> bool: """Summary line. Extended description of function. Args: arg1: Description of arg1 arg2: Description of arg2 Returns: Description of return value """ return True
Typen in Docstrings:
def func(arg1, arg2): """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
Bemerkung
PEP 484#suggested-syntax-for-python-2-7-and-straddling-code are currently not supported by Sphinx and do not appear in the generated documentation.
sphinx.ext.napoleon
#
Die Sphinx-Erweiterung sphinx.ext.napoleon ermöglicht euch, verschiedene Abschnitte in Docstrings zu definieren, einschließlich:
Attributes
Example
Keyword Arguments
Methods
Parameters
Warning
Yield
Es gibt zwei Arten von docstrings in sphinx.ext.napoleon
:
Der Hauptunterschied besteht darin, dass Google Einrückungen verwendet und NumPy Unterstreichungen:
Google:
def func(arg1, arg2): """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:
def func(arg1, arg2): """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
Detaillierte Konfigurationsoptionen findet ihr in sphinxcontrib.napoleon.Config.