mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
405ef96d2a
A builder is uniquely identified by its name, which can be used as an
entry point in the 'sphinx.builders' entry point group. This obviates
the need to register the builder as an extension.
The built-in builders are still loaded as before. New third-party builders
should provide an entry point in their setup.py:
entry_points={
'sphinx.builders': [
'mybuilder = mypackage.mymodule:MyBuilder',
],
}
Like before, builders should define a setup(app) function in the
'mypackage.module' module to define configuration variables etc. It is
no longer necessary to register the builder using Sphinx.add_builder().
Existing builders can still be loaded the traditional way, by including
their module name in the extensions list in conf.py.
87 lines
3.2 KiB
ReStructuredText
87 lines
3.2 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.
|
|
|
|
Discovery of builders by entry point
|
|
------------------------------------
|
|
|
|
.. versionadded:: 1.6
|
|
|
|
:term:`Builder` extensions can be discovered by means of `entry points`_ so
|
|
they do not have to be listed in the :confval:`extensions` configuration value.
|
|
|
|
Builder extensions need to define an entry point in the ``sphinx.builders``
|
|
group. The name of the entry point needs to be set to the name of the builder,
|
|
which is the name passed to the :option:`sphinx-build -b` option. Here is an
|
|
example of how an entry point for 'mybuilder' can be defined in ``setup.py``::
|
|
|
|
setup(
|
|
# ...
|
|
entry_points={
|
|
'sphinx.builders': [
|
|
'mybuilder = mypackage.mymodule:MyBuilder',
|
|
],
|
|
}
|
|
)
|
|
|
|
It is no longer strictly necessary to register the builder using
|
|
:meth:`~.Sphinx.add_builder` in the extension's ``setup()`` function, but it is
|
|
recommended to not remove this in order to ensure backward compatiblity.
|
|
|
|
.. _entry points: https://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins
|
|
|
|
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
|
|
collectorapi
|
|
markupapi
|
|
domainapi
|
|
parserapi
|
|
nodes
|
|
logging
|