とある 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 の属性を見つけたら消去するというものです。これを入れることで冗長なドキュメントをシンプルにできます1。
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 で処理すると次のように変換されます。
新しい機能を使ってスマートなコード、スマートなドキュメントを目指していきましょう。
-
一方、このアプローチは autodoc は何も指定しないと属性をアルファベット順に並び替えてしまうので、namedtuple の位置と属性名のマッピングがわかりづらくなるという弱点もあります。Sphinx本体でどうようの対応を行うべきかはちょっと迷っています。 ↩