Sphinx

提纲

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

描述

sphinx-apidoc 是一个用于自动生成Sphinx源代码的工具，它使用 autodoc 扩展，以其他自动API文档工具的风格记录整个包。

MODULE_PATH 是要记录的Python包的路径，以及 OUTPUT_PATH 是放置生成的源代码的目录。任何 EXCLUDE_PATTERN S给出的是 fnmatch-style 将从生成中排除的文件和/或目录模式。

警告

sphinx-apidoc 生成源文件，该文件使用 sphinx.ext.autodoc 以记录所有找到的模块。如果任何模块在导入时有副作用，这些模块将由 autodoc 什么时候 sphinx-build 就是奔跑。

如果您记录脚本(与库模块相对)，请确保它们的主例程受 if __name__ == '__main__' 条件。

选项

-o <OUTPUT_PATH>

放置输出文件的目录。如果它不存在，则创建它。

-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项目 (conf.py ， Makefile 等)使用与 sphinx-quickstart 。

-e, --separate

将每个模块的文档放在各自的页面上。

Added in version 1.2.

-E, --no-headings

不要为模块/包创建标题。例如，当文档字符串已经包含标题时，这很有用。

-P, --private

包括“_Private”模块。

Added in version 1.2.

--implicit-namespaces

如果没有这个选项， sphinx-apidoc 搜索 sys.path 对于包含以下内容的Python包 __init__.py 文件或单文件Python模块。

此选项相反使用 PEP 420 允许布局路径的隐式命名空间 foo/bar/module.py 或 foo/bar/baz/__init__.py (note的 bar 和 foo 是名称空间，而不是模块）。

-M, --module-first

将模块文档放在子模块文档之前。

在下列情况下使用这些选项 --full 已指定：

-a

将MODULE_PATH附加到sys.Path。

-H <project>

设置要放入生成的文件中的项目名称(请参见 project )。

-A <author>

设置要放入生成的文件中的作者姓名(S)(请参见 copyright )。

-V <version>

设置要放入生成的文件中的项目版本(请参见 version )。

-R <release>

将项目版本设置为放入生成的文件中(请参见 release )。

项目模板

Added in version 2.2: Sphinx-apidoc的项目模板选项

-t, --templatedir=TEMPLATEDIR

模板文件的模板目录。您可以修改apidoc生成的sphinx项目文件的模板。允许使用以下JJIA2模板文件：

  • 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)