sphinx-apidoc

概要

sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN ...]

説明

sphinx-apidoc is a tool for automatic generation of Sphinx sources that, using the autodoc extension, document a whole package in the style of other automatic API documentation tools.

MODULE_PATH is the path to a Python package to document, and OUTPUT_PATH is the directory where the generated sources are placed. Any EXCLUDE_PATTERNs given are fnmatch-style file and/or directory patterns that will be excluded from generation.

警告

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

もしあなたが (ライブラリモジュールではなく) スクリプトをドキュメント化したいのであれば、スクリプトのメインルーチンが if __name__ == '__main__' 条件により保護されていることを確認して下さい。

オプション

-o <OUTPUT_PATH>

Directory to place the output files. If it does not exist, it is created.

-q

標準出力に何も出力しないようになります。警告やエラーのみが標準エラー出力に書き出されます。

-f, --force

Force overwriting of any existing generated files.

-l, --follow-links

Follow symbolic links. Defaults to False.

-n, --dry-run

Do not create or remove any files.

-s <suffix>

Suffix for the source files generated. Defaults to rst.

-d <MAXDEPTH>

Maximum depth for the generated table of contents file. Defaults to 4.

--tocfile

Filename for a table of contents file. Defaults to modules.

-T, --no-toc

Do not create a table of contents file. Ignored when --full is provided.

--remove-old

Remove existing files in the output directory that are not created anymore. Not compatible with --full.

-F, --full

Generate a full Sphinx project (conf.py, Makefile etc.) using the same mechanism as sphinx-quickstart.

-e, --separate

Put documentation for each module on its own page.

Added in version 1.2.

-E, --no-headings

Do not create headings for the modules/packages. This is useful, for example, when docstrings already contain headings.

-P, --private

Include "_private" modules.

Added in version 1.2.

--implicit-namespaces

By default sphinx-apidoc processes sys.path searching for modules only. Python 3.3 introduced PEP 420 implicit namespaces that allow module path structures such as foo/bar/module.py or foo/bar/baz/__init__.py (notice that bar and foo are namespaces, not modules).

Interpret paths recursively according to PEP-0420.

-M, --module-first

Put module documentation before submodule documentation.

These options are used when --full is specified:

-a

Append module_path to sys.path.

-H <project>

生成したファイルに含めるプロジェクト名を指定します ( project も参照)。

-A <author>

生成したファイルに含める著者名を指定します ( copyright も参照)。

-V <version>

生成したファイルに含めるプロジェクトのバージョンを指定します ( version も参照)。

-R <release>

生成したファイルに含めるプロジェクトのリリースを指定します ( release も参照)。

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

Added in version 2.2: Project templating options for sphinx-apidoc

-t, --templatedir=TEMPLATEDIR

Template directory for template files. You can modify the templates of sphinx project files generated by apidoc. Following Jinja2 template files are allowed:

  • 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

In detail, please refer the system template files Sphinx provides. (sphinx/templates/apidoc and sphinx/templates/quickstart)

環境

SPHINX_APIDOC_OPTIONS

A comma-separated list of option to append to generated automodule directives. Defaults to members,undoc-members,show-inheritance.

参考

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