[PYTHON] Comment écrire un document tuple nommé en 2020

J'ai appris d'un PR que l'attribut namedtuple est automatiquement défini sur la docstring "Alias for field number xx".

$ 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'

Si vous traitez cette classe avec Sphinx (autodoc) et générez un document, le document suivant sera généré.

Bien que la quantité d'informations soit faible, j'ai créé un document qui utilise du papier.

Regarder en arrière

Approche pour effacer docstring

La solution de contournement pour ce problème est le code introduit dans Suppression des docstrings namedtuple pour Sphinx. Si vous trouvez l'attribut de namedtuple, supprimez-le. En incluant cela, vous pouvez simplifier les documents redondants [^ 1].

[^ 1]: D'un autre côté, cette approche présente l'inconvénient que le mappage entre la position du nom de l'élément et le nom de l'attribut est difficile à comprendre car autodoc trie les attributs par ordre alphabétique si rien n'est spécifié. Je ne sais pas trop quoi faire du Sphinx lui-même.

Une approche pour écrire la documentation des attributs avec docstring

Aussi, dans Comment écrire une docstring pour créer un document tuple nommé avec sphinx, l'approche d'écriture du document de chaque attribut avec la docstring de la classe générée est adoptée. Introduit.

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``.
    """

Je vois, vous pouvez insérer n'importe quelle description dans ce cas.

Comment écrivez-vous maintenant?

Vous pouvez contrôler librement le document de différentes manières avec docstring, mais le code est redondant. Si vous avez Python 3.6 ou supérieur et Sphinx 2.4 disponibles, c'est un peu plus simple à écrire.

En utilisant les annotations de variables introduites dans Python 3.6, namedtuple et sa documentation peuvent être écrits comme suit:

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

Et si vous utilisez Sphinx 2.4, le commentaire #: attaché à cette annotation de variable sera interprété comme une docstring, donc si vous traitez le code ci-dessus avec Sphinx, il sera converti comme suit.

Visons le code intelligent et les documents intelligents avec de nouvelles fonctionnalités.