扩展¶
由于许多项目在文档中需要特殊功能，因此 Sphinx 允许在构建过程中添加“扩展”，每个扩展都可以修改文档处理的几乎所有方面。
本章介绍了 Sphinx 附带的扩展。有关编写自定义扩展的 API 文档，请参阅 Sphinx API.
内置扩展¶
这些扩展是内置的，可以通过 extensions 配置值中的相应条目来激活。
sphinx.ext.autodoc– 从文档字符串中包含文档sphinx.ext.autosectionlabel– 允许使用标题引用部分sphinx.ext.autosummary– 生成 autodoc 摘要sphinx.ext.coverage– 收集文档覆盖率统计信息sphinx.ext.doctest– 测试文档中的代码片段sphinx.ext.duration– 测量 Sphinx 处理过程的持续时间sphinx.ext.extlinks– 标记用于缩短外部链接sphinx.ext.githubpages– 在 GitHub Pages 中发布 HTML 文档sphinx.ext.graphviz– 添加 Graphviz 图表sphinx.ext.ifconfig– 根据配置包含内容sphinx.ext.imgconverter– 使用 Imagemagick 的参考图像转换器sphinx.ext.inheritance_diagram– 包含继承图sphinx.ext.intersphinx– 链接到其他项目的文档sphinx.ext.linkcode– 添加到源代码的外部链接- Sphinx 中 HTML 输出的数学支持
sphinx.ext.napoleon– 支持 NumPy 和 Google 风格的文档字符串sphinx.ext.todo– 支持待办事项sphinx.ext.viewcode– 添加到突出显示的源代码的链接
第三方扩展¶
您可以在 sphinx-contrib 组织中找到用户贡献的多个扩展。如果您希望将您的扩展包含在此组织中，只需按照 github-administration 项目中提供的说明进行操作即可。这是可选的，并且还有多个扩展托管在其他地方。 awesome-sphinxdoc 和 sphinx-extensions 项目都是 Sphinx 包的精选列表，许多包使用 Framework :: Sphinx :: Extension 和 Framework :: Sphinx :: Theme 分别用于 Sphinx 扩展和主题的 trove 分类器。
将自定义扩展放在哪里？¶
特定于项目的扩展应放在项目的目录结构中。相应地设置 Python 的模块搜索路径 sys.path，以便 Sphinx 能够找到它们。例如，如果您的扩展 foo.py 位于项目根目录的 exts 子目录中，则将其放入 conf.py 中
import sys, os
sys.path.append(os.path.abspath('exts'))
extensions = ['foo']
您也可以将扩展安装在 sys.path 上的任何其他位置，例如在 site-packages 目录中。