mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
3dd256fe7d
- use the entry point to load the extension module in the usual way - update the documentation to reflect this change
89 lines
3.2 KiB
ReStructuredText
89 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
|
|
that they do not have to be listed in the :confval:`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
|
|
:attr:`~.Builder.name` attribute, which is the name passed to the
|
|
:option:`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
|
|
:meth:`~.Sphinx.add_builder` in the extension's :func:`setup` function.
|
|
|
|
.. _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
|