2020年におけるnamedtupleのドキュメントの書き方

とある PR がきっかけで、namedtuple の属性には "Alias for field number xx" という docstring が自動的に設定されるということを知りました。

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

このクラスを Sphinx(autodoc) で処理してドキュメントを生成すると次のようなドキュメントが生成されます。

情報量が少ない割には紙面を使うドキュメントができてしまいました。

振り返り

docstring を消すアプローチ

この問題への対策としては Removing namedtuple docstrings for Sphinx で紹介されているコードがあります。namedtuple の属性を見つけたら消去するというものです。これを入れることで冗長なドキュメントをシンプルにできます¹。

docstring で属性のドキュメントを書くアプローチ

また、namedtupleのドキュメントをsphinxで作成するためのdocstringの書き方 では、生成したクラスの docstring で各属性のドキュメントを記述するというアプローチが紹介されています。

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

なるほど、これなら任意の説明文を差し込めますね。

いまならどう書く?

docstring でいろいろ書くやりかたは自由にドキュメントをコントロールできるのですが、コードとしては冗長です。
もしあなたが Python3.6 以上と Sphinx 2.4 を利用できるのであれば、もう少しシンプルに書けます。

Python 3.6 から導入された変数アノテーションを利用すると、namedtuple とそのドキュメントが次のように書けます。

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

そして、Sphinx 2.4 を利用するとこの変数アノテーションについた #: コメントを docstring として解釈するので、上記のコードを Sphinx で処理すると次のように変換されます。

新しい機能を使ってスマートなコード、スマートなドキュメントを目指していきましょう。

1. 一方、このアプローチは autodoc は何も指定しないと属性をアルファベット順に並び替えてしまうので、namedtuple の位置と属性名のマッピングがわかりづらくなるという弱点もあります。Sphinx本体でどうようの対応を行うべきかはちょっと迷っています。 ↩