- Home
- Get it
- Docs
- Extend/Develop

# 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.

## Discovery of builders by entry point

New in version 1.6.

Builder extensions can be discovered by means of entry points so that they do not have to be listed in the `extensions` configuration value.

Builder extensions should define an entry point in the `sphinx.builders` group. The name of the entry point needs to match your builder’s `name` attribute, which is the name passed to the `sphinx-build -b` option. The entry point value should equal the dotted name of the extension module. Here is an example of how an entry point for ‘mybuilder’ can be defined in the extension’s `setup.py`:

    setup(
        # ...
        entry_points={
            'sphinx.builders': [
                'mybuilder = my.extension.module',
            ],
        }
    )

Note that it is still necessary to register the builder using `add_builder()` in the extension’s `setup()` function.

## Extension metadata

New in version 1.3.

The `setup()` function can return a dictionary. This is treated by Sphinx as metadata of the extension. Metadata keys currently recognized are:

- `'version'`: a string that identifies the extension version. It is used for extension version requirement checking (see `needs_extensions`) and informational purposes. If not given, `"unknown version"` is substituted.
- `'parallel_read_safe'`: a boolean that specifies if parallel reading of source files can be used when the extension is loaded. It defaults to `False`, i.e. you have to explicitly specify your extension to be parallel-read-safe after checking that it is.
- `'parallel_write_safe'`: a boolean that specifies if parallel writing of output files can be used when the extension is loaded. Since extensions usually don’t negatively influence the process, this defaults to `True`.

## APIs used for writing extensions

- Tutorial: Writing a simple extension
  - Important objects
  - Build Phases
  - Extension Design
  - The Setup Function
  - The Node Classes
  - The Directive Classes
  - The Event Handlers
- Application API
  - Extension setup
  - Emitting events
  - Producing messages / logging
  - Sphinx core events
  - Checking the Sphinx version
  - The Config object
  - The template bridge
  - Exceptions
- Build environment API
- Builder API
- Environment Collector API
- Docutils markup API
  - Roles
  - Directives
    - ViewLists
    - Parsing directive content as ReST
- Domain API
- Parser API
- Doctree node classes added by Sphinx
  - Nodes for domain-specific object descriptions
  - New admonition-like constructs
  - Other paragraph-level nodes
  - New inline nodes
  - Special nodes
- Logging API