Pythonでモジュール定数を文書化する方法は？

質問

モジュールを持っています。 errors.py で、いくつかのグローバル定数が定義されています（注：Pythonが定数を持たないことは理解していますが、私は慣習的にUPPERCASEを使ってそれらを定義しています）。

"""Indicates some unknown error."""
API_ERROR = 1

"""Indicates that the request was bad in some way."""
BAD_REQUEST = 2

"""Indicates that the request is missing required parameters."""
MISSING_PARAMS = 3

reStructuredTextを使用して、これらの定数をどのように文書化すればよいのでしょうか？ご覧のように、私はそれらの上にdocstringをリストアップしましたが、私はそれを行うことを示す任意のドキュメントを見つけられませんでした、私はちょうど推測としてそれをしました。

どのように解決するのですか？

残念ながら、変数（と定数）にはdocstringがありません。結局のところ、変数は単なる整数の名前であり、数値に docstring を付けたいとは思わないでしょう。 1 という数字にdocstringを付けたいとは思わないでしょう。

stdlib のほとんどのモジュールを見てみると、例えば pickle のように、stdlib のほとんどすべてのモジュールを見てみると、彼らが使っている唯一のドキュメントがコメントであることがわかるでしょう。そして、そう、それはつまり help(pickle) はこれを示しているだけです。

DATA
    APPEND = b'a'
    APPENDS = b'e'
    …

... コメントは完全に無視します。もしあなたのドキュメントをビルトインヘルプに表示させたいなら、モジュールのdocstringにそれらを追加しなければならず、それは必ずしも理想的ではありません。

しかし、Sphinxはビルトインヘルプができる以上のことをすることができます。定数のコメントを抽出するように設定したり、あるいは autodata を使って半自動的に行うこともできます。例えば

#: Indicates some unknown error.
API_ERROR = 1

複数 #: の行を代入文の前に置くか、あるいは単一の #: のコメントは、実質的に autodoc によってピックアップされたオブジェクトの docstring と同じように動作します。これは、インライン rST を処理し、変数名の rST ヘッダーを自動生成することを含みます。

副次的なメモとして、あなたは enum のような定数ではなく、のような定数を使用することを検討するとよいでしょう。Python 3.4 を使っていない場合 (おそらくまだ使っていないでしょうが...) は、Python 3.4 に対応した backport.enum パッケージがありますし、3.2+なら flufl.enum (これは同一ではありませんが、stdlib モジュールの主なインスピレーションとなったので、似ています) を 2.6+ 用に提供しています。

列挙型インスタンス( flufl.enum ではなく、stdlib/backport バージョン) は、docstring を持つこともできます。

class MyErrors(enum.Enum):
    """Indicates some unknown error."""
    API_ERROR = 1

    """Indicates that the request was bad in some way."""
    BAD_REQUEST = 2

    """Indicates that the request is missing required parameters."""
    MISSING_PARAMS = 3

には残念ながら表示されませんが help(MyErrors.MISSING_PARAMS) に表示されますが、それらはSphinx autodocが拾うことができるdocstringです。