mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
b6269d3790
Co-authored-by: Chris Sewell <chrisj_sewell@hotmail.com> Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
92 lines
2.4 KiB
ReStructuredText
92 lines
2.4 KiB
ReStructuredText
.. _writing-builders:
|
|
|
|
Builder API
|
|
===========
|
|
|
|
.. currentmodule:: sphinx.builders
|
|
|
|
.. class:: Builder
|
|
|
|
This is the base class for all builders.
|
|
|
|
It follows this basic workflow:
|
|
|
|
.. graphviz:: /_static/diagrams/sphinx_build_flow.dot
|
|
:caption: Call graph for the standard Sphinx build workflow
|
|
|
|
.. rubric:: Overridable Attributes
|
|
|
|
These class attributes should be set on builder sub-classes:
|
|
|
|
.. autoattribute:: name
|
|
.. autoattribute:: format
|
|
.. autoattribute:: epilog
|
|
.. autoattribute:: allow_parallel
|
|
.. autoattribute:: supported_image_types
|
|
.. autoattribute:: supported_remote_images
|
|
.. autoattribute:: supported_data_uri_images
|
|
.. autoattribute:: default_translator_class
|
|
|
|
.. rubric:: Core Methods
|
|
|
|
These methods define the core build workflow and must not be overridden:
|
|
|
|
.. automethod:: build_all
|
|
.. automethod:: build_specific
|
|
.. automethod:: build_update
|
|
.. automethod:: build
|
|
.. automethod:: read
|
|
.. automethod:: read_doc
|
|
.. automethod:: write_doctree
|
|
.. automethod:: write
|
|
|
|
.. rubric:: Abstract Methods
|
|
|
|
These must be implemented in builder sub-classes:
|
|
|
|
.. automethod:: get_outdated_docs
|
|
.. automethod:: write_doc
|
|
.. automethod:: get_target_uri
|
|
|
|
.. rubric:: Overridable Methods
|
|
|
|
These methods can be overridden in builder sub-classes:
|
|
|
|
.. automethod:: init
|
|
.. automethod:: write_documents
|
|
.. automethod:: prepare_writing
|
|
.. automethod:: copy_assets
|
|
.. automethod:: get_relative_uri
|
|
.. automethod:: finish
|
|
|
|
.. rubric:: Attributes
|
|
|
|
Attributes that are callable from the builder instance:
|
|
|
|
.. attribute:: events
|
|
|
|
An :class:`.EventManager` object.
|
|
|
|
.. rubric:: Overridable Attributes (extensions)
|
|
|
|
Builder sub-classes can set these attributes to support built-in extensions:
|
|
|
|
.. attribute:: supported_linkcode
|
|
:type: str
|
|
|
|
By default, the :mod:`linkcode <sphinx.ext.linkcode>` extension will
|
|
only inject references for an ``html`` builder.
|
|
The ``supported_linkcode`` class attribute can be defined in a
|
|
non-HTML builder to support managing references generated by linkcode.
|
|
The expected value for this attribute is an expression
|
|
which is compatible with :rst:dir:`only`.
|
|
|
|
For example, if a builder was named ``custom-builder``,
|
|
the following can be used:
|
|
|
|
.. code-block:: python
|
|
|
|
class CustomBuilder(Builder):
|
|
supported_linkcode = 'custom-builder'
|
|
...
|