扩展¶
由于许多项目在文档中需要特殊功能,Sphinx允许在构建过程中添加”扩展”,每个扩展可以修改文档处理的几乎任何方面.
本章描述了与Sphinx捆绑的扩展.有关编写您自己的扩展的API文档,请参阅:ref:dev-extensions .
内置扩展¶
这些扩展是内置的,可以通过 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 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扩展和主题.
将您自己的扩展放在哪里?¶
项目本地的扩展应该放在项目的目录结构中.相应地设置 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 目录中.