扩展

Since many projects will need special features in their documentation, Sphinx is designed to be extensible on several levels.

This is what you can do in an extension: First, you can add new 创建器s to support new output formats or actions on the parsed documents. Then, it is possible to register custom reStructuredText roles and directives, extending the markup. And finally, there are so-called “hook points” at strategic places throughout the build process, where an extension can register a hook and run specialized code.

An extension is simply a Python module. When an extension is loaded, Sphinx imports this module and executes its setup() function, which in turn notifies Sphinx of everything the extension offers – see the extension tutorial for examples.

The configuration file itself can be treated as an extension if it contains a setup() function. All other extensions to load must be listed in the extensions configuration value.

• 教程: 写一个简单的扩展
  • 构建阶段
  • 扩展设计
  • 设置函数
  • 节点类
  • 指令类
  • 事件处理
• 扩展接口
  • Sphinx核心事件
  • 模板桥
  • 域接口
• 写新的创建器

内置扩展

These extensions are built in and can be activated by respective entries in the extensions configuration value:

• sphinx.ext.autodoc – 从文档字符串包含文件
  • Docstring preprocessing
  • Skipping members
• sphinx.ext.autosummary – 生成autodoc摘要
  • sphinx-autogen – generate autodoc stub pages
  • Generating stub pages automatically
  • Customizing templates
• sphinx.ext.doctest – 测试文档中的片段
• sphinx.ext.intersphinx – 链接其他项目文档
• Sphinx的数学支持
  • sphinx.ext.pngmath – Render math as PNG images
  • sphinx.ext.mathjax – Render math via JavaScript
  • sphinx.ext.jsmath – Render math via JavaScript
• sphinx.ext.graphviz – 添加Graphviz图形
• sphinx.ext.inheritance_diagram – 包含继承图
• sphinx.ext.refcounting – 跟踪引用计数行为
• sphinx.ext.ifconfig – 包含基于配置的内容
• sphinx.ext.coverage – 收藏文档覆盖统计
• sphinx.ext.todo – 支持待办事项
• sphinx.ext.extlinks – 标记，以缩短外部链接
• sphinx.ext.viewcode – 给高亮显示的源代码添加链接
• sphinx.ext.linkcode – 添加源代码的外部链接
• sphinx.ext.oldcmarkup – 旧的C标记的兼容性扩展

第三方扩展

You can find several extensions contributed by users in the Sphinx Contrib repository. It is open for anyone who wants to maintain an extension publicly; just send a short message asking for write permissions.

There are also several extensions hosted elsewhere. The Wiki at BitBucket maintains a list of those.

If you write an extension that you think others will find useful or you think should be included as a part of Sphinx, please write to the project mailing list (join here).

如何放置扩展?

Extensions local to a project should be put within the project’s directory structure. Set Python’s module search path, sys.path, accordingly so that Sphinx can find them. E.g., if your extension foo.py lies in the exts subdirectory of the project root, put into conf.py:

import sys, os

sys.path.append(os.path.abspath('exts'))

extensions = ['foo']

You can also install extensions anywhere else on sys.path, e.g. in the site-packages directory.