Developing extensions for Sphinx¶
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 builders 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.
- Tutorial: Writing a simple extension
- Application API
- Build environment API
- Builder API
- Docutils markup API
- Domain API
- Doctree node classes added by Sphinx