mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
56 lines
2.1 KiB
ReStructuredText
56 lines
2.1 KiB
ReStructuredText
.. _dev-extensions:
|
|
|
|
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
|
|
:term:`builder`\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
|
|
:confval:`extensions` configuration value.
|
|
|
|
Extension metadata
|
|
------------------
|
|
|
|
.. versionadded:: 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 :confval:`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
|
|
--------------------------------
|
|
|
|
.. toctree::
|
|
|
|
tutorial
|
|
appapi
|
|
envapi
|
|
builderapi
|
|
markupapi
|
|
domainapi
|
|
nodes
|