sphinx-apidoc

概要

sphinx-apidoc [オプション] -o <出力パス> <モジュールパス> [除外パターン …]

説明

sphinx-apidoc は、autodoc 拡張機能を使用して、他の自動APIドキュメントツールと同様のスタイルでパッケージ全体をドキュメント化するSphinxソースを自動生成するためのツールです。

モジュールパスはドキュメント化するPythonパッケージへのパス、出力パスは生成されたソースが配置されるディレクトリです。指定された除外パターンは、生成から除外されるfnmatch形式のファイルまたはディレクトリパターンです。

警告

sphinx-apidoc は、sphinx.ext.autodoc を使用して、見つかったすべてのモジュールをドキュメント化するソースファイルを生成します。インポート時に副作用を持つモジュールがある場合、sphinx-build の実行時に autodoc によって実行されます。

スクリプト（ライブラリモジュールではなく）をドキュメント化する場合は、メインルーチンが if __name__ == '__main__' 条件によって保護されていることを確認してください。

オプション

-o <出力パス>

出力ファイルを配置するディレクトリ。存在しない場合は作成されます。

-q

標準出力には何も出力せず、警告とエラーのみを標準エラーに出力します。

-f, --force

既存の生成済みファイルを強制的に上書きします。

-l, --follow-links

シンボリックリンクを辿ります。デフォルトは False です。

-n, --dry-run

ファイルを作成または削除しません。

-s <suffix>

生成されるソースファイルの拡張子。デフォルトは rst です。

-d <MAXDEPTH>

生成される目次ファイルの最大深度。デフォルトは 4 です。

--tocfile

目次ファイルのファイル名。デフォルトは modules です。

-T, --no-toc

目次ファイルを作成しません。--full が指定されている場合は無視されます。

--remove-old

出力ディレクトリに存在する、もはや作成されないファイルを削除します。--full と互換性がありません。

-F, --full

sphinx-quickstart と同じメカニズムを使用して、完全なSphinxプロジェクト（conf.py、Makefile など）を生成します。

-e, --separate

各モジュールのドキュメントを独自のページに配置します。

バージョン 1.2 で追加されました。

-E, --no-headings

モジュール/パッケージの見出しを作成しません。これは、たとえば、docstringに既に 見出しが含まれている場合に役立ちます。

-P, --private

「_private」モジュールを含めます。

バージョン 1.2 で追加されました。

--implicit-namespaces

デフォルトでは、sphinx-apidoc は sys.path を処理してモジュールのみを検索します。Python 3.3 では、PEP 420 の暗黙的な名前空間が導入され、foo/bar/module.py や foo/bar/baz/__init__.py などのモジュールパス構造が可能になりました（bar と foo は名前空間であり、モジュールではないことに注意してください）。

PEP-0420 に従ってパスを再帰的に解釈します。

-M, --module-first

サブモジュールドキュメントの前にモジュールドキュメントを配置します。

--full が指定されている場合に使用するオプション

-a

module_path を sys.path に追加します。

-H <project>

生成されたファイルに配置するプロジェクト名を設定します（project を参照）。

-A <author>

生成されたファイルに配置する作成者名を設定します（copyright を参照）。

-V <version>

生成されたファイルに配置するプロジェクトバージョンを設定します（version を参照）。

-R <release>

生成されたファイルに配置するプロジェクトリリースを設定します（release を参照）。

プロジェクトテンプレート

バージョン 2.2 で追加: sphinx-apidoc のプロジェクトテンプレートオプション

-t, --templatedir=TEMPLATEDIR

テンプレートファイルのテンプレートディレクトリ。apidoc によって生成されるsphinxプロジェクトファイルのテンプレートを変更できます。以下の Jinja2 テンプレートファイルが許可されています

  • module.rst.jinja

  • package.rst.jinja

  • toc.rst.jinja

  • root_doc.rst.jinja

  • conf.py.jinja

  • Makefile.jinja

  • Makefile.new.jinja

  • make.bat.jinja

  • make.bat.new.jinja

詳細は、Sphinx が提供するシステムテンプレートファイルを参照してください。（sphinx/templates/apidoc と sphinx/templates/quickstart）

環境変数

SPHINX_APIDOC_OPTIONS

生成された automodule ディレクティブに追加するオプションのカンマ区切りリスト。デフォルトは members,undoc-members,show-inheritance です。

関連項目

sphinx-build(1), sphinx-autogen(1)