118

デフォルトでは、Sphinx は __init__(self) のドキュメントを生成しません。私は次のことを試しました：

.. automodule:: mymodule
    :members:

と

..autoclass:: MyClass
    :members:

conf.py では、次のように設定すると、__init__(self) docstring がクラス docstring に追加されるだけです ( Sphinx の autodoc ドキュメントでは、これが予期される動作であることに同意しているようですが、解決しようとしている問題については何も言及されていません)。

autoclass_content = 'both'
4

6 に答える 6

120

3つの選択肢があります。

  1. それが常に文書化されていることを確認するために、conf.pyで__init__()使用できます。autodoc-skip-memberこのような：

    def skip(app, what, name, obj, would_skip, options):
    if name == "__init__":
        return False
    return would_skip

def setup(app):
    app.connect("autodoc-skip-member", skip)

    これは、スキップされないことを明示的に定義__init__します（デフォルトではスキップされません）。この構成は一度指定されるだけで、.rstソースのすべてのクラスに追加のマークアップは必要ありません。

  2. このspecial-membersオプションはSphinx1.1で追加されました。これにより、「特別な」メンバー（のような名前のメンバー__special__）がautodocによって文書化されます。

    Sphinx 1.2以降、このオプションは引数を取るため、以前よりも便利になります。

  3. 使用automethod：

    .. autoclass:: MyClass     
   :members: 

   .. automethod:: __init__

    automoduleこれはすべてのクラスに追加する必要があります（この回答の最初のリビジョンへのコメントで指摘されているように、と一緒に使用することはできません）。

于 2011-04-08T19:08:27.400 に答える
84

あなたは近かった。ファイルでautoclass_contentオプションを使用できます。conf.py

autoclass_content = 'both'
于 2012-03-19T15:25:06.833 に答える
7

過去数年間、私はさまざまな無関係な Python プロジェクトのコールバックのいくつかのバリアントを作成してきました。これは、やautodoc-skip-memberのようなメソッドを API ドキュメントに表示したかったからです(結局のところ、これらの「特別なメソッド」は API の一部であり、より適切な場所はありません)。特別なメソッドの docstring 内よりもそれらを文書化します)。__init__()__enter__()__exit__()

最近、私は最良の実装を採用し、それを私の Python プロジェクトの 1 つに含めました (ここにドキュメントがあります)。実装は基本的に次のようになります。

import types

def setup(app):
    """Enable Sphinx customizations."""
    enable_special_methods(app)


def enable_special_methods(app):
    """
    Enable documenting "special methods" using the autodoc_ extension.

    :param app: The Sphinx application object.

    This function connects the :func:`special_methods_callback()` function to
    ``autodoc-skip-member`` events.

    .. _autodoc: http://www.sphinx-doc.org/en/stable/ext/autodoc.html
    """
    app.connect('autodoc-skip-member', special_methods_callback)


def special_methods_callback(app, what, name, obj, skip, options):
    """
    Enable documenting "special methods" using the autodoc_ extension.

    Refer to :func:`enable_special_methods()` to enable the use of this
    function (you probably don't want to call
    :func:`special_methods_callback()` directly).

    This function implements a callback for ``autodoc-skip-member`` events to
    include documented "special methods" (method names with two leading and two
    trailing underscores) in your documentation. The result is similar to the
    use of the ``special-members`` flag with one big difference: Special
    methods are included but other types of members are ignored. This means
    that attributes like ``__weakref__`` will always be ignored (this was my
    main annoyance with the ``special-members`` flag).

    The parameters expected by this function are those defined for Sphinx event
    callback functions (i.e. I'm not going to document them here :-).
    """
    if getattr(obj, '__doc__', None) and isinstance(obj, (types.FunctionType, types.MethodType)):
        return False
    else:
        return skip

はい、ロジックよりも多くのドキュメントがあります:-)。autodoc-skip-memberオプションを使用するよりもこのようなコールバックを定義する利点はspecial-members(私にとって)、このspecial-membersオプションにより、(すべての新しいスタイルのクラスで利用可能、AFAIK) のようなプロパティのドキュメント化も可能になること__weakref__です。これはノイズであり、まったく役に立たないと考えています。コールバック アプローチはこれを回避します (関数/メソッドでのみ機能し、他の属性を無視するため)。

于 2016-02-18T22:02:40.563 に答える