Improve documentation for the Builder API (#13008)

Co-authored-by: Chris Sewell <[email protected]>
Co-authored-by: Adam Turner <[email protected]>

Author: 3 people

doc/extdev/builderapi.rst

@@ -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
@@ -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
@@ -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`.
 

sphinx/builders/__init__.py

@@ -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
@@ -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_),
@@ -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: