Skip to content

Commit

Permalink
Improve documentation for the Builder API (#13008)
Browse files Browse the repository at this point in the history
Co-authored-by: Chris Sewell <chrisj_sewell@hotmail.com>
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
  • Loading branch information
3 people authored Oct 11, 2024
1 parent c46abc4 commit b6269d3
Show file tree
Hide file tree
Showing 2 changed files with 33 additions and 18 deletions.
10 changes: 5 additions & 5 deletions doc/extdev/builderapi.rst
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Builder API

.. rubric:: Overridable Attributes

These attributes should be set on builder sub-classes:
These class attributes should be set on builder sub-classes:

.. autoattribute:: name
.. autoattribute:: format
Expand All @@ -29,8 +29,7 @@ Builder API

.. rubric:: Core Methods

These methods are predefined and should generally not be overridden,
since they form the core of the build process:
These methods define the core build workflow and must not be overridden:

.. automethod:: build_all
.. automethod:: build_specific
Expand Down Expand Up @@ -73,11 +72,12 @@ Builder API
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`` attribute can be defined in a non-HTML builder
to support managing references generated by linkcode.
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`.

Expand Down
41 changes: 28 additions & 13 deletions sphinx/builders/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -59,33 +59,39 @@ class Builder:
Builds target formats from the reST sources.
"""

#: The builder's name, for the -b command line option.
name = ''
#: The builder's name.
#: This is the value used to select builders on the command line.
name: str = ''
#: The builder's output format, or '' if no document output is produced.
format = ''
#: The message emitted upon successful build completion. This can be a
#: printf-style template string with the following keys: ``outdir``,
#: ``project``
epilog = ''
#: This is commonly the file extension, e.g. "html",
#: though any string value is accepted.
#: The builder's format string can be used by various components
#: such as :class:`.SphinxPostTransform` or extensions to determine
#: their compatibility with the builder.
format: str = ''
#: The message emitted upon successful build completion.
#: This can be a printf-style template string
#: with the following keys: ``outdir``, ``project``
epilog: str = ''

#: default translator class for the builder. This can be overridden by
#: :py:meth:`~sphinx.application.Sphinx.set_translator`.
default_translator_class: type[nodes.NodeVisitor]
# doctree versioning method
versioning_method = 'none'
versioning_compare = False
#: allow parallel write_doc() calls
allow_parallel = False
#: Whether it is safe to make parallel :meth:`~.Builder.write_doc()` calls.
allow_parallel: bool = False
# support translation
use_message_catalog = True

#: The list of MIME types of image formats supported by the builder.
#: Image files are searched in the order in which they appear here.
supported_image_types: list[str] = []
#: The builder can produce output documents that may fetch external images when opened.
supported_remote_images = False
supported_remote_images: bool = False
#: The file format produced by the builder allows images to be embedded using data-URIs.
supported_data_uri_images = False
supported_data_uri_images: bool = False

def __init__(self, app: Sphinx, env: BuildEnvironment) -> None:
self.srcdir = app.srcdir
Expand Down Expand Up @@ -159,7 +165,7 @@ def get_target_uri(self, docname: str, typ: str | None = None) -> str:
def get_relative_uri(self, from_: str, to: str, typ: str | None = None) -> str:
"""Return a relative URI between two source filenames.
May raise environment.NoUri if there's no way to return a sensible URI.
:raises: :exc:`!NoUri` if there's no way to return a sensible URI.
"""
return relative_uri(
self.get_target_uri(from_),
Expand Down Expand Up @@ -789,7 +795,16 @@ def copy_assets(self) -> None:
pass

def write_doc(self, docname: str, doctree: nodes.document) -> None:
"""Where you actually write something to the filesystem."""
"""
Write the output file for the document
:param docname: the :term:`docname <document name>`.
:param doctree: defines the content to be written.
The output filename must be determined within this method,
typically by calling :meth:`~.Builder.get_target_uri`
or :meth:`~.Builder.get_relative_uri`.
"""
raise NotImplementedError

def write_doc_serialized(self, docname: str, doctree: nodes.document) -> None:
Expand Down

0 comments on commit b6269d3

Please sign in to comment.