Add documentation for extensions.

docs/composers.rst

@@ -3,10 +3,10 @@
 Composers
 =========
 
-``handroll`` uses a plugin system to decide how to process each file type. The
+handroll uses a plugin system to decide how to process each file type. The
 plugins are called composers. A composer is provided a source file and can
-produce whatever output it desires.  ``handroll`` will load each available
-composer using ``setuptools`` entry points. ``handroll`` loads the class and
+produce whatever output it desires.  handroll will load each available
+composer using ``setuptools`` entry points. handroll loads the class and
 constructs a ``Composer`` instance by invoking a no parameter constructor.
 
 .. autoclass:: handroll.composers.Composer

docs/configuration.rst

@@ -21,6 +21,10 @@ configuration file option.
 The ``outdir`` option will determine the output directory. If a tilde character
 (``~``) is supplied, it will be expanded to the user's home directory.
 
+The ``with_blog`` option set to ``true``, ``on``, ``yes``, or ``1`` will
+enable the blog extension.
+See :ref:`blogextension` for setup information.
+
 .. _frontmatter:
 
 Front matter

docs/extensions.rst

@@ -0,0 +1,42 @@
+.. _extensions:
+
+Extensions
+==========
+
+In addition to :ref:`composers`, handroll has an extension system
+to plug in other functionality.
+Users enable extensions
+by adding ``with_* = true`` to their ``site`` section
+in the configuration file,
+where ``*`` is the name of the extension.
+For example, the blog extension is named ``blog``,
+and ``with_blog = true`` will enable it.
+
+Extension authors can use the base ``Extension``
+to create new extensions.
+Extensions are never directly called,
+but an extension can connect to one of handroll's :ref:`signals`.
+
+.. autoclass:: handroll.extensions.base.Extension
+
+Extension authors can include new extensions by adding to the
+``handroll.extensions`` entry point. For example, handroll includes
+the following entry point in ``setup.py``:
+
+.. code-block:: python
+
+   entry_points={
+       'handroll.extensions': [
+           'blog = handroll.extensions.blog:BlogExtension',
+       ]
+   }
+
+Built-in extensions
+===================
+
+.. _blogextension:
+
+Blog extension
+--------------
+
+.. autoclass:: handroll.extensions.blog.BlogExtension

docs/index.rst

@@ -48,6 +48,7 @@ what handroll is capable of doing.
 * Generate a proper `Atom XML
   <http://en.wikipedia.org/wiki/Atom_%28standard%29>`_ feed from metadata
   stored in JSON.
+* Track blog entries and automatically generate a feed.
 * Run a development server with the ``watch`` flag to monitor your site and
   update the output immediately as you make changes (see :ref:`devserver`).
 * Find the site source root so you don't have to. If you're anywhere in your
@@ -63,7 +64,7 @@ what handroll is capable of doing.
   than the existing output file. This eliminates wasted regeneration on
   unchanged content.
 * Be extensible for users who want to write their own plugins (see
-  :ref:`composers`).
+  :ref:`composers` and :ref:`extensions`).
 * Provide timing information to see file processing time.
 * Translated to many different languages.
 
@@ -79,6 +80,7 @@ Documentation
     configuration
     server
     composers
+    extensions
     signals
     templates
     i18n

docs/signals.rst

@@ -1,3 +1,5 @@
+.. _signals:
+
 Signals
 =======