web-dev-qa-db-ja.com

Sphinx autodocは十分に自動ではありません

Pythonで5,000以上のラインプロジェクトを文書化するためにSphinxを使用しようとしています。約7つの基本モジュールがあります。私の知る限り、autodocを使用するには、プロジェクトの各ファイルに対して次のようなコードを記述する必要があります。

.. automodule:: mods.set.tests
    :members:
    :show-inheritance:

私は多くのファイルを持っているので、これはあまりにも退屈です。 「mods」パッケージをドキュメント化することを指定できると、はるかに簡単になります。その後、Sphinxはパッケージを再帰的に処理し、各サブモジュールのページを作成できます。

このような機能はありますか？そうでない場合は、すべての.rstファイルを作成するスクリプトを作成できますが、それには多くの時間がかかります。

pythonpython-sphinx
137
Cory Walker

これを確認できます script 私が作ったもの。私はそれがあなたを助けることができると思います。

このスクリプトは、ディレクトリツリーを解析してpythonモジュールとパッケージを探し、ReSTファイルを適切に作成してSphinxでコードドキュメントを作成します。モジュールインデックスも作成します。

[〜＃〜] update [〜＃〜]

このスクリプトは、apidocとしてSphinx 1.1の一部になりました。

130
Etienne

Sphinxに元の質問が行われたときに autosummary 拡張子があったかどうかはわかりませんが、今のところ、sphinx-apidocなどを使用せずにその種の自動生成を設定することはかなり可能ですスクリプト。以下に、私のプロジェクトの1つで機能する設定があります。

  1. conf.pyファイルでautosummary拡張機能（およびautodoc）を有効にし、autosummary_generateオプションをTrueに設定します。カスタム*.rstテンプレートを使用していない場合、これで十分かもしれません。それ以外の場合、テンプレートディレクトリを除外リストに追加します。そうしないと、autosummaryがテンプレートを入力ファイルとして扱います（これはバグのようです）。

    extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary']
autosummary_generate = True
templates_path = [ '_templates' ]
exclude_patterns = ['_build', '_templates']

  2. autosummary::ファイルのTOCツリーでindex.rstを使用します。この例では、モジュールproject.module1およびproject.module2のドキュメントが自動的に生成され、_autosummaryディレクトリに配置されます。

    PROJECT
=======

.. toctree::

.. autosummary::
   :toctree: _autosummary

   project.module1
   project.module2

  3. デフォルトでは、autosummaryはモジュールとその機能の非常に短い要約のみを生成します。これを変更するには、カスタムテンプレートファイルを_templates/autosummary/module.rst（ Jinja2 で解析されます）に入れることができます：

    {{ fullname }}
{{ underline }}

.. automodule:: {{ fullname }}
    :members:

結論として、_autosummaryディレクトリをバージョン管理下に置く必要はありません。また、任意の名前を付けてソースツリーの任意の場所に配置することもできます（ただし、_buildの下に置くと機能しません）。

32
firegurafiku

各パッケージでは、__init__.pyファイルには.. automodule:: package.moduleパッケージの各部分のコンポーネント。

その後、.. automodule:: packageそして、それはほとんどあなたが望むことをします。

11
S.Lott

たぶんあなたが探しているのは Epydoc とこれ Sphinx拡張 です。

1
Edward Dale