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:

.. automodule::
.. autoclass::
.. autoefunction::

Diese dokumentieren ein Modul, eine Klasse oder eine Funktion unter Verwendung des jeweiligen Docstrings.

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.

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.