扩展

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

本章介绍 Sphinx 捆绑的扩展。 有关编写您自己的扩展的 API 文档，请参阅 Sphinx API。

内置扩展

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

第三方扩展

您可以在 sphinx-contrib 组织中找到用户贡献的多个扩展。 如果您希望将您的扩展包含在此组织中，只需按照 github-administration 项目中提供的说明进行操作即可。 这是可选的，并且还有一些扩展托管在其他地方。awesome-sphinxdoc 和 sphinx-extensions 项目都是 Sphinx 包的精选列表，许多包都使用 Framework :: Sphinx :: Extension 和 Framework :: Sphinx :: Theme trove 分类器分别用于 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 目录中。