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::
.. autofunction::

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

Siehe auch

PEP 257

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 Typ-Tester 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.