调用sphinx-quickstart ¶
sphinx-quickstart脚本生成一个Sphinx文档集。它像这样调用：
$ sphinx-quickstart [options] [projectdir]
其中projectdir是你要放置的Sphinx文档集目录。如果你省略projectdir，默认情况下会将文件生成到当前目录中。
sphinx-quickstart脚本具有几个选项：
-
-h,--help,--version¶ 显示用法概要或Sphinx版本。
结构上的选项¶
-
--sep¶ 如果指定，则分开源目录和构建目录。
-
--dot=DOT¶ 在根目录内，将创建另外两个目录； “_templates”用于自定义HTML模板，“_static”用于自定义样式表和其他静态文件。你可以输入另一个前缀（例如”.”）来替换下划线。
项目的基本选项¶
-
--suffix=SUFFIX¶ 源文件后缀。（参见
source_suffix）。
-
--master=MASTER¶ 主文档名称。（参见
master_doc）。
-
--epub¶ 使用epub。
扩展的选项¶
-
--ext-autodoc¶ 启用
sphinx.ext.autodoc扩展。
-
--ext-doctest¶ 启用
sphinx.ext.doctest扩展。
-
--ext-intersphinx¶
-
--ext-todo¶ 启用
sphinx.ext.todo扩展。
-
--ext-coverage¶ 启用
sphinx.ext.coverage扩展。
-
--ext-imgmath¶ 启用
sphinx.ext.imgmath扩展。
-
--ext-mathjax¶ 启用
sphinx.ext.mathjax扩展。
-
--ext-ifconfig¶ 启用
sphinx.ext.ifconfig扩展。
-
--ext-viewcode¶ 启用
sphinx.ext.viewcode扩展。
-
--extensions=EXTENSIONS¶ 启用任意的扩展。
调用sphinx-build ¶
sphinx-build脚本构建一个Sphinx文档集。It is called like this:
$ sphinx-build [options] sourcedir builddir [filenames]
其中sourcedir是源目录，builddir是你要放置构建好的文档的目录。大多数情况下，你不需要指定任何filenames。
sphinx-build脚本有几个选项：
-
-bbuildername¶ 最重要的选项：它选择一个构建器。最常见的构建器是：
- html
- 构建HTML页面。这是默认构建器。
- dirhtml
- 构建HTML页面，但每个文档有一个目录。如果从网页服务器提供服务，能生成更漂亮的URL（无
.html）。 - singlehtml
- 使用整个内容构建单个HTML。
- htmlhelp, qthelp, devhelp, epub
- 构建HTML文件，以及构建这些格式的文档集合的附加信息。
- applehelp
- 构建Apple帮助文档。需要hiutil和codesign，这些不是开源，目前仅在Mac OS X 10.6及更高版本中可用。
- latex
- 构建可以使用pdflatex编译为PDF文档的LaTeX源。
- man
- 为UNIX系统构建groff格式的手册页。
- texinfo
- 创建可以使用makeinfo处理为Info文件的Texinfo文件。
- text
- 构建纯文本文件。
- gettext
- 构建gettext样式的消息目录（
.pot文件）。 - doctest
- 如果启用了
doctest扩展，在文档中运行所有doctests。 - linkcheck
- 检查所有外部链接的完整性。
- xml
- 构建Docutils原生XML文件。
- pseudoxml
- 构建紧凑的漂亮打印的“伪XML”文件，显示中间文档树的内部结构。
有关Sphinx附带的所有构建器的列表，请参见可用的构建器。扩展可以添加自己的构建器。
-
-a¶ 如果给定，始终写入所有输出文件。默认仅为新的和更改过的源文件写入输出文件。（这可能不适用于所有构建器。）
-
-ttag¶ 定义tag标记。This is relevant for
onlydirectives that only include their content if this tag is set.版本0.6中的新功能。
-
-dpath¶ 由于Sphinx必须先读取并解析所有源文件，然后才能写入输出文件，所以解析的源文件将缓存为“doctree pickles”。通常，这些文件放在build目录下名为
.doctrees的目录中；使用此选项你可以选择不同的缓存目录（doctrees可以在所有构建器之间共享）。
-
-jN¶ 在N个进程上并行分发构建，以使在多处理器机器上构建更有效。请注意，不是所有的部分以及所有的Sphinx的构建器都可以并行化。
版本1.2中的新功能：应认为此选项是实验性的。
-
-cpath¶ 不要在源目录中查找
conf.py，而应使用给定的配置目录。注意，由配置值给出的各种其他文件和路径应该相对于配置目录，因此它们也必须存在于该位置。版本0.3中的新功能。
-
-C¶ 不要查找配置文件；只能通过
-D选项选择。版本0.5中的新功能。
-
-Dsetting=value¶ 覆盖在
conf.py文件中设置的配置值。该值必须是数字、字符串、列表或字典值。对于列表，你可以使用逗号分隔元素，例如：
-D html_theme_path=path1,path2。对于字典值，请提供设置名称和键如下：
-D latex_elements.docclass=scrartcl。对于布尔值，使用
0或1作为值。在版本0.6中更改：该值现在可以是字典值。
在版本1.3中更改：该值现在也可以是列表值。
-
-Aname=value¶ 在HTML模板中将name赋值为value。
版本0.5中的新功能。
-
-n¶ 以nit-picky模式运行。目前，这会为所有缺失的引用生成警告。有关将某些引用排除为“已知缺失”的方法，请参阅配置值
nitpick_ignore。
-
-N¶ 不要产生彩色输出。
-
-q¶ 不要在标准输出上输出任何内容，只能将警告和错误写入标准错误。
-
-Q¶ 不要在标准输出上输出任何内容，也会抑制警告。只有错误写入标准错误。
-
-wfile¶ 除了标准错误之外，还会向给定文件写入警告（和错误）。
-
-W¶ 将警告转为错误。这意味着构建会在第一个警告时退出，且
sphinx-build退出状态为1。
-
-T¶ 发生未处理的异常时显示完整的回溯。否则，仅显示摘要，并且回溯信息保存到文件以供进一步分析。
版本1.2中的新功能。
-
-P¶ （仅用于调试。）如果在构建时发生未处理的异常，则运行Python调试器
pdb。
-
-h,--help,--version¶ 显示用法概要或Sphinx版本。
版本1.2中的新功能。
你也可以在命令行上的源和构建目录之后给出一个或多个文件名。然后，Sphinx将尝试仅构建这些输出文件（及其依赖项）。
调用sphinx-apidoc ¶
sphinx-apidoc为Python包生成完全自动的API文档。它这样调用：
$ sphinx-apidoc [options] -o outputdir packagedir [pathnames]
其中packagedir是要文档化的包的路径，outputdir是产生的源文件所在的目录。Any pathnames given are paths to be excluded ignored during generation.
警告
sphinx-apidoc生成使用sphinx.ext.autodoc文档化所有找到的模块的reST文件。如果任何模块在导入时有副作用，则在运行sphinx-build时，它们将由autodoc执行。
如果你文档化的是脚本（而不是库模块），确保它们的主例程受到if __name__ == '__main__'条件保护。
sphinx-apidoc脚本有几个选项：
-
-ooutputdir¶ 提供放置生成的输出的目录。
-
-f,--force¶ 通常，sphinx-apidoc不会覆盖任何文件。使用此选项强制覆盖其生成的所有文件。
-
-n,--dry-run¶ 使用此选项，将不会写入任何文件。
-
-ssuffix¶ 此选项选择输出文件的文件名后缀。默认情况下，它是
rst。
-
-dmaxdepth¶ 这将设置目录的最大深度（如果生成一个目录）。
-
-l,--follow-links¶ 此选项使sphinx-apidoc递归文件系统以发现包和模块时跟踪符号链接。如果你想从由collective.recipe.omelette管理的源目录生成文档，则可能需要它。默认情况下，跳过符号链接。
版本1.2中的新功能。
-
-F,--full¶ 此选项使sphinx-apidoc创建一个完整的Sphinx项目，使用与sphinx-quickstart相同的机制。大多数配置值都设置为默认值，但你可以使用以下选项来影响最重要的值。
-
--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¶ 此选项使得sphinx-apidoc将模块文档放在子模块文档之前。
-
-a¶ 将module_path附加到sys.path。