延拓¶
由于许多项目的文档中都需要特殊功能,因此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样式的文档字符串sphinx.ext.todo
--支持待办事项sphinx.ext.viewcode
--添加指向突出显示的源代码的链接
第三方扩展¶
您可以在中找到多个由用户贡献的扩展 sphinx-contrib 组织。如果您希望在此组织中包括您的分机,只需按照中提供的说明进行操作 github-administration 项目。这是可选的,有几个扩展托管在其他地方。这个 awesome-sphinxdoc 和 sphinx-extensions 项目都是Sphinx包的精选列表,许多包使用 Framework :: Sphinx :: Extension 和 Framework :: Sphinx :: Theme 分别用于Sphinx扩展和主题的Trove分类器。
把你自己的分机放在哪里?¶
项目的本地扩展应该放在项目的目录结构中。设置Python的模块搜索路径, sys.path
,这样狮身人面像就能找到它们。例如,如果您的分机 foo.py
存在于 exts
项目根目录的子目录,放入 conf.py
**
import sys, os
sys.path.append(os.path.abspath('exts'))
extensions = ['foo']
您也可以在上的其他位置安装扩展模块 sys.path
,例如在 site-packages
目录。