Write the doc on extending themes.

docs/first_theme.rst

@@ -9,7 +9,10 @@ Creating a theme proceeds as `documented in the Nikola reference
 the template features that nti.nikola_chameleon provides. Make sure
 you've read :doc:`getting_started` before reading this.
 
-Your theme should be laid out according to the Nikola documentation..
+Your theme should be laid out according to the Nikola documentation.
+You'll need to specify ``nti.nikola_chameleon`` as the ``engine`` in
+your theme meta file.
+
 The only directory that nti.nikola_chameleon is interested in is your
 ``templates/`` folder.
 

docs/inheritance.rst

@@ -2,6 +2,75 @@
  Theme Inheritance
 ===================
 
-.. todo:: Write inheritance.
+nti.nikola_chameleon support themes that extend themes. In fact, with
+a well designed and documented base theme, nti.nikola_chameleon makes
+it easy to customize as much or as little as you'd like.
 
-Talk about how and why. Overloading bits and pieces. ZCA makes it easy.
+Extending a theme is just like :doc:`creating a theme <first_theme>`.
+The only difference is that you need to specify the ``parent`` theme
+that you're extending by name. For example, here's the theme meta file
+for the ``bootstrap3-chamaleon`` theme, which extends the
+``base-chameleon`` theme:
+
+.. code-block:: ini
+   :emphasize-lines: 9
+
+   [Theme]
+   engine = nti.nikola_chameleon
+   author = NextThought
+   author_url =
+   license = Apache2
+   based_on = Bootstrap 3 <https://getbootstrap.com/>
+   tags = bootstrap
+   parent = base-chameleon
+
+   [Family]
+   family = bootstrap3
+
+   [Nikola]
+   bootswatch = True
+
+From that point on, you can override and customize the necessary
+pieces of the theme. Specifically how you do that will depend on the
+theme you're extending.
+
+Replacing Files
+===============
+
+If you have a ``*.tmpl.pt`` with the same name as one from the parent
+theme, your file will replace that file when it is used as :ref:`a
+template name by Nikola <lookup-templates>` and when it is used as
+:ref:`a view name <finding-views>` for the purposes of using macros.
+(Make sure you define the necessary macros!) This is a little bit
+blunt, so we don't usually recommend replacing entire files (or using
+file views to find macro names for that matter).
+
+Replacing Macros
+================
+
+Any macros you define with the same name (and specificity) as macros
+defined by the parent theme will replace the parent theme macros. For
+example, any macros defined in ``*.macro.pt`` files in your theme will
+override such macros defined in ``*.macro.pt`` files in the parent
+theme (because macros defined that way all have the same, very low,
+specificity).
+
+You can override a macro of a given name for only *some* kinds of
+objects with an appropriate definition in your :ref:`theme.zcml
+<lookup-macros>`.
+
+Extending and Replacing Viewlets
+================================
+
+Adding to or replacing viewlets defined in the parent theme is the
+same as doing so :ref:`in a single theme <multiple-viewlets>`: just
+pay attention to the names and the specificity of your viewlet declarations.
+
+ZCML Execution
+==============
+
+The ``theme.zcml`` files are executed from the base theme down to the
+most derived theme. The execution context is the same for each
+execution, so base themes can `provide features
+<http://zopeconfiguration.readthedocs.io/en/latest/narr.html#making-specific-directives-conditional>`_
+that child themes can test for.

docs/using_zca.rst

@@ -112,10 +112,13 @@ Component Lookup
 ================
 
 Now that we know about the three key objects, we can talk about
-exactly why they are so key and how they are used. (In short, they are
+exactly why they are so key and how they are used. In short, they are
 used for component lookup through the system, and it is this layer of
 indirection that permits us flexibility and allows for easy
-:doc:`inheritance`.)
+:doc:`inheritance`. Or to put it more pragmatically, they allow us to
+*declaratively configure* how templates are composed and used, instead
+of creating a `mess of spaghetti code
+<https://getnikola.com/theming.html#identifying-and-customizing-different-kinds-of-pages-with-a-shared-template>`_.
 
 Throughout, we will use the example of Nikola rendering a page (not a
 blog post) in a system that has Disqus comments enabled.

docs/viewlets.rst

@@ -30,7 +30,11 @@ Viewlet Managers and the ``provider:`` Expression
 =================================================
 
 We'll jump right in with an example from the ``base-chameleon`` theme.
-First, here is a (simplified) template called ``generic_post_list.pt``::
+First, here is a (simplified) template called
+``generic_post_list.pt``:
+
+.. code-block:: xml
+   :emphasize-lines: 5
 
     <html xmlns:tal="http://xml.zope.org/namespaces/tal"
           xmlns:metal="http://xml.zope.org/namespaces/metal">
@@ -60,9 +64,12 @@ attribute (if one exists) set to a false value.
 
 So that's the first step in using viewlets (after deciding where in
 the template viewlets might be useful, of course): define your viewlet
-manager. This is done in ZCML::
+manager. This is done in ZCML:
+
+.. code-block:: xml
+   :emphasize-lines: 10,11
 
-  <configure xmlns="http://namespaces.zope.org/zope"
+   <configure xmlns="http://namespaces.zope.org/zope"
              xmlns:i18n="http://namespaces.zope.org/i18n"
              xmlns:zcml="http://namespaces.zope.org/zcml"
              xmlns:z3c="http://namespaces.zope.org/z3c"
@@ -145,9 +152,12 @@ Now that we have a viewlet manager, we can add individual viewlets to
 it. For our purposes, a viewlet is a template that gets run to fill in
 a piece of content for its viewlet manager. Recall that viewlets are
 associated with viewlet manager via the viewlet manager's kind, or interface.
-Again, this is done in ZCML::
+Again, this is done in ZCML:
 
-  <configure xmlns="http://namespaces.zope.org/zope"
+.. code-block:: xml
+   :emphasize-lines: 11,12,13,20,21,22
+
+   <configure xmlns="http://namespaces.zope.org/zope"
              xmlns:i18n="http://namespaces.zope.org/i18n"
              xmlns:zcml="http://namespaces.zope.org/zcml"
              xmlns:z3c="http://namespaces.zope.org/z3c"
@@ -189,9 +199,12 @@ Passing Parameters
 
 Notice that they both use the same ``template`` argument. And what's
 that ``article_class`` attribute for? Let's take a look at that
-template file, ``v_generic_article_post_list.pt``::
+template file, ``v_generic_article_post_list.pt``:
+
+.. code-block:: xml
+   :emphasize-lines: 1
 
-  <article class="${view/article_class}"
+    <article class="${view/article_class}"
            xmlns:tal="http://xml.zope.org/namespaces/tal"
 	       xmlns:metal="http://xml.zope.org/namespaces/metal">
       <header>
@@ -201,7 +214,7 @@ template file, ``v_generic_article_post_list.pt``::
       <ul metal:use-macro="macro:html_posts_postlist">
           <li>A post</li>
       </ul>
-  </article>
+    </article>
 
 It turns out that all the extra attributes you specify in ZCML get
 turned into attributes on the ``view`` object when the viewlet runs.
@@ -218,6 +231,7 @@ template was called.
              view, access to the type of comment system in use is lost
              when rendering a viewlet.
 
+.. _multiple-viewlets:
 
 Overwriting, Extending, and Multiple Viewlets
 =============================================