扩展

由于许多项目在其文档中都需要特殊的特性，Sphinx允许在构建过程中添加“扩展”，每个扩展几乎可以修改文档处理的任何方面。

本章描述了与Sphinx捆绑在一起的扩展。有关编写自己扩展名的API文档，请参阅 Sphinx扩展API .

内置扩展

这些扩展是内置的，可以通过 extensions 配置值：

• sphinx.ext.autodoc --包括文档字符串中的文档
• sphinx.ext.autosectionlabel --允许引用节使用其标题
• sphinx.ext.autosummary --生成自动生成摘要
• sphinx.ext.coverage --收集文档覆盖率统计
• sphinx.ext.doctest --文档中的测试片段
• sphinx.ext.duration --测量 Sphinx 处理的持续时间
• sphinx.ext.extlinks --缩短外部链接的标记
• sphinx.ext.githubpages --在GitHub页面中发布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风格的docstrings
• sphinx.ext.todo --对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 目录。