扩展

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

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

内置扩展

这些扩展是内置的，可以通过 extensions 配置值中的相应条目激活

第三方扩展

你可以在 sphinx-contrib 组织中找到用户贡献的几个扩展。如果你希望将你的扩展包含在这个组织中，只需按照 github-administration 项目中提供的说明操作。这是可选的，还有一些扩展托管在其他地方。awesome-sphinxdoc 和 sphinx-extensions 项目都是 Sphinx 包的精选列表，许多包使用 Framework :: Sphinx :: Extension 和 Framework :: Sphinx :: Theme 归类器分别用于 Sphinx 扩展和主题。

把你的扩展放在哪里？

项目本地的扩展应该放在项目的目录结构中。相应地设置 Python 的模块搜索路径 sys.path，以便 Sphinx 可以找到它们。例如，如果你的扩展 foo.py 位于项目根目录的 exts 子目录中，请在 conf.py 中添加

import sys
from pathlib import Path

sys.path.append(str(Path('exts').resolve()))

extensions = ['foo']

你也可以将扩展安装在 sys.path 上的任何其他位置，例如在 site-packages 目录中。