Merged in ericholscher/sphinx (pull request #150)

A pull request with some developer documentation updates

doc/ext/tutorial.rst

@@ -174,7 +174,7 @@ A directive class is a class deriving usually from
 doesn't exist yet in Docutils 0.4, Sphinx has another base class called
 ``sphinx.util.compat.Directive`` that you can derive your directive from, and it
 will work with both Docutils 0.4 and 0.5 upwards.  The directive interface is
-covered in detail in the docutils documentation; the important thing is that the
+covered in detail in the `docutils documentation`_; the important thing is that the
 class has a method ``run`` that returns a list of nodes.
 
 The ``todolist`` directive is quite simple::
@@ -341,3 +341,4 @@ an italic node) with the backreference.  The reference URI is built by
 used builder, and appending the todo node's (the target's) ID as the anchor
 name.
 
+.. _docutils documentation: http://docutils.sourceforge.net/docs/ref/rst/directives.html

sphinx/builders/__init__.py

@@ -385,9 +385,11 @@ class Builder(object):
             t.join()
 
     def prepare_writing(self, docnames):
+        """A place where you can add logic before :meth:`write_doc` is run"""
         raise NotImplementedError
 
     def write_doc(self, docname, doctree):
+        """Where you actually write something to the filesystem."""
         raise NotImplementedError
 
     def write_doc_serialized(self, docname, doctree):

sphinx/writers/html.py

@@ -28,6 +28,8 @@ except ImportError:
     except ImportError:
         Image = None
 
+# A good overview of the purpose behind these classes can be found here:
+# http://www.arnebrodowski.de/blog/write-your-own-restructuredtext-writer.html
 
 class HTMLWriter(Writer):
     def __init__(self, builder):