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::#
.. autoexception::#

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.