8

拡張機能でsphinxを使用しており、文書化されたメンバーではなく、いくつかのモジュールで文書化されていないメンバー関数のみautodocを含むリストを生成したいと考えています。

次のように、文書化されたメンバーと文書化されていないメンバーの両方を含むリストを正常に作成できます。

.. automodule:: module
    :members:
    :undoc-members:

ディレクティブを単独で使用する:members:と、予想どおり、文書化されたメンバーのみのリストが作成されます。

.. automodule:: module
    :members:

しかし、:undoc-members:ディレクティブだけを使用した場合 (つまり、フラグを省略した:members:場合) は、まったくリストになりません。

.. automodule:: module
    :undoc-members:

これを自動的に生成する方法はありますか？

(主要なドキュメントには、ドキュメント化されたすべてのメンバーを表示するページが含まれていますが、ドキュメント化されていないメンバーをすべてリストする単一のページを作成することで、各関数などのドキュメントを作成したことを確認する方がはるかに便利です。それらのテキストは表示されません)文書化されています）。

4

2 に答える 2

6

イベントをオーバーライドするとautodoc-process-docstring(@delnan が指摘)、以下を に追加すると役立ちますconf.py。

# set up the types of member to check that are documented
members_to_watch = ['function',];

def warn_undocumented_members(app, what, name, obj, options, lines):
    if(what in members_to_watch and len(lines)==0):
        # warn to terminal during build
        print "Warning: ", what, "is undocumented: ", name, "(%d)"% len(lines);
        # or modify the docstring so the rendered output is highlights the omission
        lines.append(".. Warning:: %s '%s' undocumented" % (what, name));

そして、この関数をイベントに接続します (この SO スレッドの回答から):

def setup(app):
    app.connect('autodoc-process-docstring', warn_undocumented_members);

オン（オフ）にするには、警告に undoc-members を含めます（除外します）- in でグローバルautodoc_default_flagsにconf.py、または質問のように両方のディレクティブを使用します。

autodoc_default_flags = ['members', 'undoc-members' ]
#autodoc_default_flags = ['members' ]

編集：

次の方法で、このアプローチを拡張して undoc メンバーだけを生成しようとしました。

  • 条件付きwarn_undoc=Trueで、関数の実行中にオブジェクトにプロパティを設定しますwarn_undocumented_members(上記) 。
  • 設定されていないautodoc-skip-member場合にすべてのメンバーをスキップするプリプロセッサ イベントに 2 番目のオーバーライド関数をアタッチします。warn_undoc

autodoc-skip-memberただし、発生する前にメンバーのグループごとに発生するため、さらに調査すると、このアプローチは除外されautodoc-process-docstringます。したがって、docstring の有無に基づいて条件付きでスキップするには、プロパティの設定が遅すぎます。

于 2013-01-09T15:16:56.233 に答える