扩展

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

本章介绍与Sphinx捆绑在一起的扩展。有关编写自己的扩展的API文档,请参阅 为Sphinx开发扩展

内置扩展

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

第三方扩展

待处理

这应该现在引用自GitHub组织

您可以在 Sphinx Contrib 存储库中找到用户贡献的几个扩展。它对任何想要公开维护扩展的人开放;只需发送一条要求写入权限的短消息。

其他地方也有几个扩展。 Sphinx扩展调查awesome-sphinxdoc 包含一个全面的列表。

如果您编写了一个您认为其他人会认为有用的扩展程序,或者您认为应该将其作为Sphinx的一部分包含在内,请写入项目邮件列表(加入这里)。

在哪里放置自己的扩展?

项目本地的扩展应放在项目的目录结构中。相应地设置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 目录中。