[PYTHON] Wie schreibe ich ein benanntes Tupeldokument im Jahr 2020?

Ich habe von einem PR erfahren, dass das Attribut namedtuple automatisch auf die Dokumentzeichenfolge "Alias für Feldnummer xx" gesetzt wird.

$ python
Python 3.8.1 (default, Feb 13 2020, 13:34:23)
[Clang 11.0.0 (clang-1100.0.33.17)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> from collections import namedtuple
>>>
>>> Coordinate = namedtuple('Coordinate', 'X Y')
>>> Coordinate.__doc__
'Coordinate(X, Y)'
>>> Coordinate.X.__doc__
'Alias for field number 0'
>>> Coordinate.Y.__doc__
'Alias for field number 1'

Wenn Sie diese Klasse mit Sphinx (Autodoc) verarbeiten und ein Dokument generieren, wird das folgende Dokument generiert.

Obwohl die Informationsmenge gering ist, habe ich ein Dokument erstellt, das Papier verwendet.

Zurückblicken

Ansatz zum Löschen der Dokumentzeichenfolge

Die Problemumgehung für dieses Problem ist der Code, der in Entfernen von namedtuple-Dokumentzeichenfolgen für Sphinx eingeführt wurde. Wenn Sie das Attribut namedtuple finden, löschen Sie es. Indem Sie dies einbeziehen, können Sie redundante Dokumente vereinfachen [^ 1].

[^ 1]: Andererseits hat dieser Ansatz den Nachteil, dass die Zuordnung zwischen der Position des benannten Tupels und dem Attributnamen schwer zu verstehen ist, da Autodoc die Attribute alphabetisch sortiert, wenn nichts angegeben ist. Ich bin ein wenig verwirrt darüber, was ich mit Sphinx selbst machen soll.

Ein Ansatz zum Schreiben von Attributdokumentationen mit docstring

In So schreiben Sie eine Dokumentzeichenfolge zum Erstellen eines benannten Tupeldokuments mit Sphinx wird der Ansatz zum Schreiben des Dokuments jedes Attributs mit der Dokumentzeichenfolge der generierten Klasse übernommen. Eingeführt.

class NamedTupleWithDocstring2(namedtuple("NamedTuple", "aaa bbb ccc")):
    """
    hogehoge

    .. py:attribute:: aaa

        Description of the ``aaa``.

    .. py:attribute:: bbb

        Description of the ``bbb``.

    .. py:attribute:: ccc

        Description of the ``ccc``.
    """

Ich sehe, Sie können in diesem Fall jede Beschreibung einfügen.

Wie schreibst du jetzt?

Sie können das Dokument mit docstring auf verschiedene Arten frei schreiben, aber der Code ist redundant. Wenn Sie Python 3.6 oder höher und Sphinx 2.4 zur Verfügung haben, ist das Schreiben etwas einfacher.

Mithilfe der in Python 3.6 eingeführten Variablenanmerkungen können namedtuple und seine Dokumentation wie folgt geschrieben werden:

from typing import NamedTuple

class Coordinate(NamedTuple):
    """A 2-dimension coordinate."""

    X: float  #: the coordinate on X-axis
    Y: float  #: the coordinate on Y-axis

Wenn Sie Sphinx 2.4 verwenden, wird der an diese Variablenanmerkung angehängte Kommentar "#:" als Dokumentzeichenfolge interpretiert. Wenn Sie also den obigen Code mit Sphinx verarbeiten, wird er wie folgt konvertiert.

Streben wir nach intelligentem Code und intelligenten Dokumenten mit neuen Funktionen.