`sphinx.ext.napoleon` – Unterstützung für NumPy und Google-Docstrings¶

Modulautor: Rob Ruana

Hinzugefügt in Version 1.3.

Übersicht¶

Haben Sie es satt, Docstrings wie diese zu schreiben?

:param path: The path of the file to wrap
:type path: str
:param field_storage: The :class:`FileStorage` instance to wrap
:type field_storage: FileStorage
:param temporary: Whether or not to delete the file when the File
   instance is destructed
:type temporary: bool
:returns: A buffered writable file descriptor
:rtype: BufferedFileStorage

reStructuredText ist großartig, aber es erzeugt visuell dichte, schwer lesbare Docstrings. Vergleichen Sie das Durcheinander oben mit demselben, das gemäß dem Google Python Style Guide neu geschrieben wurde

Args:
    path (str): The path of the file to wrap
    field_storage (FileStorage): The :class:`FileStorage` instance to wrap
    temporary (bool): Whether or not to delete the file when the File
       instance is destructed

Returns:
    BufferedFileStorage: A buffered writable file descriptor

Viel besser lesbar, nicht wahr?

Napoleon ist eine Erweiterung, die Sphinx in die Lage versetzt, sowohl NumPy als auch Google-Style-Docstrings zu parsen – dem von Khan Academy empfohlenen Stil.

Napoleon ist ein Vorprozessor, der NumPy und Google-Style-Docstrings parst und sie in reStructuredText umwandelt, bevor Sphinx versucht, sie zu parsen. Dies geschieht in einem Zwischenschritt, während Sphinx die Dokumentation verarbeitet, sodass keine der Docstrings in Ihren tatsächlichen Quellcodedateien geändert werden.

Erste Schritte¶

Nachdem Sie Sphinx eingerichtet haben, um Ihre Dokumentation zu erstellen, aktivieren Sie napoleon in der Sphinx-Datei conf.py
```
# conf.py

# Add napoleon to the extensions list
extensions = ['sphinx.ext.napoleon']
```
Verwenden Sie sphinx-apidoc, um Ihre API-Dokumentation zu erstellen
```
$ sphinx-apidoc -f -o docs/source projectdir
```

Docstrings¶

Napoleon interpretiert jeden Docstring, den autodoc finden kann, einschließlich Docstrings für: Module, Klassen, Attribute, Methoden, Funktionen und Variablen. Innerhalb jedes Docstrings werden speziell formatierte Abschnitte geparst und in reStructuredText umgewandelt.

Alle Standard-reStructuredText-Formatierungen funktionieren weiterhin wie erwartet.

Docstring-Abschnitte¶

Alle folgenden Abschnittsüberschriften werden unterstützt

Args (Alias von Parameters)
Arguments (Alias von Parameters)
Aufmerksamkeit
Attribute
Vorsicht
Danger
Error
Beispiel
Beispiele
Hinweis
Wichtig
Keyword Args (Alias von Keyword Arguments)
Keyword Arguments
Methoden
Hinweis
Hinweise
Other Parameters
Parameters
Return (Alias von Returns)
Returns
Raise (Alias von Raises)
Raises
References
See Also
Tipp
Todo
Warnung
Warnings (Alias von Warning)
Warn (Alias von Warns)
Warns
Yield (Alias von Yields)
Yields

Google vs NumPy¶

Napoleon unterstützt zwei Docstring-Stile: Google und NumPy. Der Hauptunterschied zwischen den beiden Stilen ist, dass Google Einrückungen zur Trennung von Abschnitten verwendet, während NumPy Unterstriche verwendet.

Google-Stil

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-Stil

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

Der NumPy-Stil erfordert tendenziell mehr vertikalen Platz, während der Google-Stil mehr horizontalen Platz verwendet. Der Google-Stil ist tendenziell leichter lesbar für kurze und einfache Docstrings, während der NumPy-Stil tendenziell leichter lesbar für lange und detaillierte Docstrings ist.

Die Wahl zwischen den Stilen ist weitgehend ästhetisch, aber die beiden Stile sollten nicht gemischt werden. Wählen Sie einen Stil für Ihr Projekt und seien Sie konsequent damit.

Siehe auch

Für vollständige Beispiele

Typ-Annotationen¶

PEP 484 führte eine Standardmethode zur Angabe von Typen in Python-Code ein. Dies ist eine Alternative zur direkten Angabe von Typen in Docstrings. Ein Vorteil der Typangabe gemäß PEP 484 ist, dass Typüberprüfer und IDEs sie für die statische Codeanalyse nutzen können. PEP 484 wurde dann durch PEP 526 erweitert, das eine ähnliche Methode zur Annotation von Variablen (und Attributen) einführte.

Google-Stil mit Typ-Annotationen

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

class Class:
    """Summary line.

    Extended description of class

    Attributes:
        attr1: Description of attr1
        attr2: Description of attr2
    """

    attr1: int
    attr2: str

Google-Stil mit 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

class Class:
    """Summary line.

    Extended description of class

    Attributes:
        attr1 (int): Description of attr1
        attr2 (str): Description of attr2
    """

Konfiguration¶

Im Folgenden sind alle von napoleon verwendeten Einstellungen und ihre Standardwerte aufgeführt. Diese Einstellungen können in der Sphinx-Datei conf.py geändert werden. Stellen Sie sicher, dass „sphinx.ext.napoleon“ in conf.py aktiviert ist

# conf.py

# Add any Sphinx extension module names here, as strings
extensions = ['sphinx.ext.napoleon']

# Napoleon settings
napoleon_google_docstring = True
napoleon_numpy_docstring = True
napoleon_include_init_with_doc = False
napoleon_include_private_with_doc = False
napoleon_include_special_with_doc = True
napoleon_use_admonition_for_examples = False
napoleon_use_admonition_for_notes = False
napoleon_use_admonition_for_references = False
napoleon_use_ivar = False
napoleon_use_param = True
napoleon_use_rtype = True
napoleon_preprocess_types = False
napoleon_type_aliases = None
napoleon_attr_annotations = True

napoleon_google_docstring¶

Typ:: bool
Standard:: True

True, um Google-Style-Docstrings zu parsen. False, um die Unterstützung für Google-Style-Docstrings zu deaktivieren.

napoleon_numpy_docstring¶

Typ:: bool
Standard:: True

True, um NumPy-Style-Docstrings zu parsen. False, um die Unterstützung für NumPy-Style-Docstrings zu deaktivieren.

napoleon_include_init_with_doc¶

Typ:: bool
Standard:: False

True, um __init___-Docstrings getrennt vom Klassen-Docstring aufzulisten. False, um auf das Standardverhalten von Sphinx zurückzufallen, das den __init___-Docstring als Teil der Klassendokumentation betrachtet.

Wenn True:

def __init__(self):
    """
    This will be included in the docs because it has a docstring
    """

def __init__(self):
    # This will NOT be included in the docs

napoleon_include_private_with_doc¶

Typ:: bool
Standard:: False

True, um private Member (wie _membername) mit Docstrings in die Dokumentation aufzunehmen. False, um auf das Standardverhalten von Sphinx zurückzufallen.

Wenn True:

def _included(self):
    """
    This will be included in the docs because it has a docstring
    """
    pass

def _skipped(self):
    # This will NOT be included in the docs
    pass

napoleon_include_special_with_doc¶

Typ:: bool
Standard:: True

True, um spezielle Member (wie __membername__) mit Docstrings in die Dokumentation aufzunehmen. False, um auf das Standardverhalten von Sphinx zurückzufallen.

Wenn True:

def __str__(self):
    """
    This will be included in the docs because it has a docstring
    """
    return unicode(self).encode('utf-8')

def __unicode__(self):
    # This will NOT be included in the docs
    return unicode(self.__class__.__name__)

napoleon_use_admonition_for_examples¶

Typ:: bool
Standard:: False

True, um die Direktive .. admonition:: für die Abschnitte **Example** und **Examples** zu verwenden. False, um stattdessen die Direktive .. rubric:: zu verwenden. Je nachdem, welches HTML-Theme verwendet wird, kann das eine besser aussehen als das andere.

Dieser NumPy-Style-Snippet wird wie folgt konvertiert:

Example
-------
This is just a quick example

Wenn True:

.. admonition:: Example

   This is just a quick example

Wenn False:

.. rubric:: Example

This is just a quick example

napoleon_use_admonition_for_notes¶

Typ:: bool
Standard:: False

True, um die Direktive .. admonition:: für **Notes**-Abschnitte zu verwenden. False, um stattdessen die Direktive .. rubric:: zu verwenden.

Hinweis

Der singuläre Abschnitt **Note** wird immer in eine Direktive .. note:: konvertiert.

Siehe auch

napoleon_use_admonition_for_examples

napoleon_use_admonition_for_references¶

Typ:: bool
Standard:: False

True, um die Direktive .. admonition:: für **References**-Abschnitte zu verwenden. False, um stattdessen die Direktive .. rubric:: zu verwenden.

Siehe auch

napoleon_use_admonition_for_examples

napoleon_use_ivar¶

Typ:: bool
Standard:: False

True, um die Rolle :ivar: für Instanzvariablen zu verwenden. False, um stattdessen die Direktive .. attribute:: zu verwenden.

Dieser NumPy-Style-Snippet wird wie folgt konvertiert:

Attributes
----------
attr1 : int
    Description of `attr1`

Wenn True:

:ivar attr1: Description of `attr1`
:vartype attr1: int

Wenn False:

.. attribute:: attr1

   Description of `attr1`

   :type: int

napoleon_use_param¶

Typ:: bool
Standard:: True

True, um eine :param:-Rolle für jeden Funktionsparameter zu verwenden. False, um eine einzelne :parameters:-Rolle für alle Parameter zu verwenden.

Dieser NumPy-Style-Snippet wird wie folgt konvertiert:

Parameters
----------
arg1 : str
    Description of `arg1`
arg2 : int, optional
    Description of `arg2`, defaults to 0

Wenn True:

:param arg1: Description of `arg1`
:type arg1: str
:param arg2: Description of `arg2`, defaults to 0
:type arg2: :class:`int`, *optional*

Wenn False:

:parameters: * **arg1** (*str*) --
               Description of `arg1`
             * **arg2** (*int, optional*) --
               Description of `arg2`, defaults to 0

napoleon_use_keyword¶

Typ:: bool
Standard:: True

True, um eine :keyword:-Rolle für jedes Schlüsselwortargument einer Funktion zu verwenden. False, um eine einzelne :keyword arguments:-Rolle für alle Schlüsselwörter zu verwenden.

Dies verhält sich ähnlich wie napoleon_use_param. Beachten Sie, dass im Gegensatz zu docutils :keyword: und :param: nicht auf die gleiche Weise behandelt werden – es wird einen separaten Abschnitt „Keyword Arguments“ geben, der auf die gleiche Weise wie der Abschnitt „Parameters“ gerendert wird (Typ-Links werden nach Möglichkeit erstellt).

Siehe auch

napoleon_use_param

napoleon_use_rtype¶

Typ:: bool
Standard:: True

True, um die Rolle :rtype: für den Rückgabetyp zu verwenden. False, um den Rückgabetyp inline mit der Beschreibung auszugeben.

Dieser NumPy-Style-Snippet wird wie folgt konvertiert:

Returns
-------
bool
    True if successful, False otherwise

Wenn True:

:returns: True if successful, False otherwise
:rtype: bool

Wenn False:

:returns: *bool* -- True if successful, False otherwise

napoleon_preprocess_types¶

Typ:: bool
Standard:: False

True, um die Typdefinitionen in den Docstrings als Referenzen zu konvertieren.

Hinzugefügt in Version 3.2.1.

Geändert in Version 3.5: Google-Style-Docstrings werden ebenfalls vorverarbeitet.

napoleon_type_aliases¶

Typ:: dict[str, str] | None
Standard:: None

Eine Zuordnung zur Übersetzung von Typnamen in andere Namen oder Referenzen. Funktioniert nur, wenn napoleon_use_param = True.

Mit

napoleon_type_aliases = {
    "CustomType": "mypackage.CustomType",
    "dict-like": ":term:`dict-like <mapping>`",
}

Dieser NumPy-Style-Snippet

Parameters
----------
arg1 : CustomType
    Description of `arg1`
arg2 : dict-like
    Description of `arg2`

wird zu

:param arg1: Description of `arg1`
:type arg1: mypackage.CustomType
:param arg2: Description of `arg2`
:type arg2: :term:`dict-like <mapping>`

Hinzugefügt in Version 3.2.

napoleon_attr_annotations¶

Typ:: bool
Standard:: True

True, um die Verwendung von PEP 526-Attribut-Annotationen in Klassen zu erlauben. Wenn ein Attribut im Docstring ohne Typ dokumentiert ist und im Klassenrumpf eine Annotation hat, wird dieser Typ verwendet.

Hinzugefügt in Version 3.4.

napoleon_custom_sections¶

Typ:: Sequence[str | tuple[str, str]] | None
Standard:: None

Fügen Sie eine Liste benutzerdefinierter Abschnitte hinzu, um die Liste der geparsten Abschnitte zu erweitern.

Die Einträge können entweder Strings oder Tupel sein, je nach Absicht

Um einen benutzerdefinierten „generischen“ Abschnitt zu erstellen, übergeben Sie einfach einen String.
Um einen Alias für einen vorhandenen Abschnitt zu erstellen, übergeben Sie ein Tupel, das den Aliasnamen und das Original in dieser Reihenfolge enthält.
Um einen benutzerdefinierten Abschnitt zu erstellen, der wie die Abschnitte Parameter oder Rückgabewerte angezeigt wird, übergeben Sie ein Tupel, das den Namen des benutzerdefinierten Abschnitts und einen String-Wert „params_style“ oder „returns_style“ enthält.

Wenn ein Eintrag nur ein String ist, wird er als Überschrift für einen generischen Abschnitt interpretiert. Wenn der Eintrag ein Tupel/Liste/indizierter Container ist, ist der erste Eintrag der Name des Abschnitts, der zweite ist der Schlüssel des zu emulierenden Abschnitts. Wenn der zweite Eintrags-Wert „params_style“ oder „returns_style“ ist, wird der benutzerdefinierte Abschnitt wie der Parameterabschnitt oder der Rückgabeabschnitt angezeigt.

Hinzugefügt in Version 1.8.

Geändert in Version 3.5: Unterstützung für params_style und returns_style

sphinx.ext.napoleon – Unterstützung für NumPy und Google-Docstrings¶

Übersicht¶

Erste Schritte¶

Docstrings¶

Docstring-Abschnitte¶

Google vs NumPy¶

Typ-Annotationen¶

Konfiguration¶

`sphinx.ext.napoleon` – Unterstützung für NumPy und Google-Docstrings¶