web-dev-qa-db-ja.com

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

モジュールがあります、errors.pyいくつかのグローバル定数が定義されています（注：Pythonには定数がないことを理解していますが、大文字を使用して慣例により定義しています）。

"""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をリストしましたが、それを行うことを示すドキュメントが見つかりませんでした。推測として行っただけです。

pythonpython-sphinxrestructuredtext
44
skyler

残念ながら、変数（および定数）にはdocstringがありません。結局のところ、変数は単なる整数の名前であり、関数またはクラスオブジェクトの場合のように、数値_1_にdocstringを添付したくないでしょう。

pickle のようなstdlibのほとんどすべてのモジュールを見ると、それらが使用する唯一のドキュメントがコメントであることがわかります。そして、はい、それはhelp(pickle)がこれを示すだけであることを意味します：

_DATA
    APPEND = b'a'
    APPENDS = b'e'
    …
_

…コメントを完全に無視します。組み込みヘルプにドキュメントを表示したい場合は、モジュールのドキュメント文字列にドキュメントを追加する必要がありますが、これは必ずしも理想的ではありません。

しかし、Sphinxは組み込みヘルプよりも多くのことができます。定数のコメントを抽出するように設定するか、 autodata を使用して半自動で行うことができます。例えば：

_#: Indicates some unknown error.
API_ERROR = 1
_

割り当てステートメントの前の複数の_#:_行、またはステートメントの右側の単一の_#:_コメントは、autodocによって選択されたオブジェクトのdocstringsと同じように効果的に機能します。これには、インラインrSTの処理、および変数名のrSTヘッダーの自動生成が含まれます。その機能を実現するために余分なことはありません。

補足として、このような個別の定数の代わりに enum を使用することを検討してください。 Python 3.4（おそらくまだ…）ではありません）を使用していない場合、3.2 +用の _backport.enum_ パッケージ、または- _flufl.enum_ （これは同一ではありませんが、stdlibモジュールの主なインスピレーションであったため、同様です）2.6以降。

Enumインスタンス（_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です。

54
abarnert

ハッシュ+コロンを使用して、属性（クラスまたはモジュールレベル）を文書化できます。

  #: Use this content as input for moo to do bar
  MY_CONSTANT = "foo"

これはピックアップsomeドキュメントジェネレーターです。

ここの例では、より良いものを見つけることができませんでした Sphinxドキュメントモジュールプロパティ

18
Mikko Ohtamaa

文字列afterを変数に入れると、sphinxはそれを変数のドキュメントとして選択します。私はあちこちでそれを行うので、それが機能することを知っています。このような：

FOO = 1
"""
Constant signifying foo.

Blah blah blah...
"""  # pylint: disable=W0105

Pylintディレクティブは、ドキュメントに影響のないステートメントであるというフラグを立てないようにpylintに指示します。

18
Louis

これは古い質問ですが、関連する回答が欠落していることに気付きました。

または、モジュールのdocstringに .. py：data :: で定数の説明を含めることができます。そのようにして、ドキュメントは対話型ヘルプからも利用可能になります。 Sphinxはこれをうまくレンダリングします。

"""
Docstring for my module.

.. data:: API_ERROR

    Indicates some unknown error.

.. data:: BAD_REQUEST

    Indicates that the request was bad in some way.

.. data:: MISSING_PARAMS

    Indicates that the request is missing required parameters.
"""
17
Robert Jørgensgaard Engdahl

ここでは運が悪いと思います。

Pythonは、変数のdocstringを直接サポートしていません。モジュール、クラス、および関数の__doc__属性のように、変数にアタッチしてインタラクティブに取得できる属性はありません。

ソース 。

2
Johnsyweb