Improve builder docs a bit.

2 files changed, 29 insertions, 7 deletions

diff --git a/doc/ext/builderapi.rst b/doc/ext/builderapi.rst
index 72c388fb..5c671f2d 100644
--- a/doc/ext/builderapi.rst
+++ b/doc/ext/builderapi.rst
@@ -20,7 +20,7 @@ Writing new builders
    .. automethod:: build_update
    .. automethod:: build
 
-   These methods must be overridden in concrete builder classes:
+   These methods can be overridden in concrete builder classes:
 
    .. automethod:: init
    .. automethod:: get_outdated_docs
@@ -28,3 +28,7 @@ Writing new builders
    .. automethod:: prepare_writing
    .. automethod:: write_doc
    .. automethod:: finish
+
+   Useful helpers:
+
+   .. automethod:: init_templates
diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py
index 04313723..4cd4c2d3 100644
--- a/sphinx/builders/__init__.py
+++ b/sphinx/builders/__init__.py
@@ -64,11 +64,18 @@ class Builder(object):
     # helper methods
 
     def init(self):
-        """Load necessary templates and perform initialization."""
+        """
+        Load necessary templates and perform initialization.  The default
+        implementation does nothing.
+        """
         pass
 
     def init_templates(self):
-        # Call this from init() if you need templates.
+        """
+        Initialize the template system.
+
+        Call this method from init() if you need templates in your builder.
+        """
         if self.config.template_bridge:
             self.templates = self.app.import_object(
                 self.config.template_bridge, 'template_bridge setting')()
@@ -79,7 +86,7 @@ class Builder(object):
 
     def get_target_uri(self, docname, typ=None):
         """
-        Return the target URI for a document name (typ can be used to qualify
+        Return the target URI for a document name (*typ* can be used to qualify
         the link characteristic for individual builders).
         """
         raise NotImplementedError
@@ -96,6 +103,10 @@ class Builder(object):
         """
         Return an iterable of output files that are outdated, or a string describing
         what an update build will build.
+
+        If the builder does not output individual files corresponding to source files,
+        return a string here.  If it does, return an iterable of those files that need
+        to be written.
         """
         raise NotImplementedError
 
@@ -197,7 +208,7 @@ class Builder(object):
         self.build(None, summary='all source files', method='all')
 
     def build_specific(self, filenames):
-        """Only rebuild as much as needed for changes in the source_filenames."""
+        """Only rebuild as much as needed for changes in the *filenames*."""
         # bring the filenames to the canonical format, that is,
         # relative to the source directory and without source_suffix.
         dirlen = len(self.srcdir) + 1
@@ -214,7 +225,7 @@ class Builder(object):
                    'line' % len(to_write))
 
     def build_update(self):
-        """Only rebuild files changed or added since last build."""
+        """Only rebuild what was changed or added since last build."""
         to_build = self.get_outdated_docs()
         if isinstance(to_build, str):
             self.build(['__all__'], to_build)
@@ -225,6 +236,10 @@ class Builder(object):
                        'out of date' % len(to_build))
 
     def build(self, docnames, summary=None, method='update'):
+        """
+        Main build method.  This first updates the environment, and then calls
+        :meth:`write`.
+        """
         if summary:
             self.info(bold('building [%s]: ' % self.name), nonl=1)
             self.info(summary)
@@ -313,7 +328,10 @@ class Builder(object):
         raise NotImplementedError
 
     def finish(self):
-        raise NotImplementedError
+        """
+        Finish the building process.  The default implementation does nothing.
+        """
+        pass
 
 
 BUILTIN_BUILDERS = {