Theming docs, part 2.

doc/config.rst

@@ -131,15 +131,16 @@ General configuration
 .. confval:: templates_path
 
    A list of paths that contain extra templates (or templates that overwrite
-   builtin templates).  Relative paths are taken as relative to the
-   configuration directory.
+   builtin/theme-specific templates).  Relative paths are taken as relative to
+   the configuration directory.
 
 .. confval:: template_bridge
 
    A string with the fully-qualified name of a callable (or simply a class) that
    returns an instance of :class:`~sphinx.application.TemplateBridge`.  This
    instance is then used to render HTML documents, and possibly the output of
-   other builders (currently the changes builder).
+   other builders (currently the changes builder).  (Note that the template
+   bridge must be made theme-aware if HTML themes are to be used.)
 
 .. confval:: rst_epilog
 
@@ -328,6 +329,14 @@ that use Sphinx' HTMLWriter class.
 
    .. versionadded:: 0.6
 
+.. confval:: html_style
+
+   The style sheet to use for HTML pages.  A file of that name must exist either
+   in Sphinx' :file:`static/` path, or in one of the custom paths given in
+   :confval:`html_static_path`.  Default is the stylesheet given by the selected
+   theme.  If you only want to add or override a few things compared to the
+   theme's stylesheet, use CSS ``@import`` to import the theme's stylesheet.
+
 .. confval:: html_title
 
    The "title" for HTML documentation generated with Sphinx' own templates.
@@ -344,13 +353,6 @@ that use Sphinx' HTMLWriter class.
 
    .. versionadded:: 0.4
 
-.. confval:: html_style
-
-   The style sheet to use for HTML pages.  A file of that name must exist either
-   in Sphinx' :file:`static/` path, or in one of the custom paths given in
-   :confval:`html_static_path`.  Default is the stylesheet given by the selected
-   theme.
-
 .. confval:: html_logo
 
    If given, this must be the name of an image file that is the logo of the

doc/theming.rst

@@ -97,11 +97,66 @@ Sphinx comes with a selection of themes to choose from:
 * **sphinxdoc** -- The theme used for this documentation.  It features a sidebar
   on the right side.  There are currently no options beyond *nosidebar*.
 
-..
- * option specs
- * zipfiles
- * old config values work
- * static/
- * theme.conf
- * _t templates
+
+Creating themes
+---------------
+
+As said, themes are either a directory or a zipfile (whose name is the theme
+name), containing the following:
+
+* A :file:`theme.conf` file, see below.
+* HTML templates, if needed.
+* A ``static/`` directory containing any static files that will be copied to the
+  output statid directory on build.  These can be images, styles, script files.
+
+The :file:`theme.conf` file is in INI format [1]_ (readable by the standard
+Python :mod:`ConfigParser` module) and has the following structure::
+
+    [theme]
+    inherit = base theme
+    stylesheet = main CSS name
+    pygments_style = stylename
+
+    [options]
+    variable = default value
+
+* The **inherit** setting gives the name of a "base theme", or ``none``.  The
+  base theme will be used to locate missing templates, its options will be
+  inherited, and all of its static files will be used as well.
+
+* The **stylesheet** setting gives the name of a CSS file which will be
+  referenced in the HTML header.  If you need more than one CSS file, either
+  include one from the other via CSS' ``@import``, or use a custom HTML template
+  that adds ``<link rel="stylesheet">`` tags as necessary.  Setting the
+  :confval:`html_style` config value will override this setting.
+
+* The **pygments_style** setting gives the name of a Pygments style to use for
+  highlighting.  This can be overridden by the user in the
+  :confval:`pygments_style` config value.
+
+* The **options** section contains pairs of variable names and default values.
+  These options can be overridden by the user in :confval:`html_theme_options`
+  and are accessible from all templates as ``theme_<name>``.
+
+
+Static templates
+----------------
+
+Since theme options are meant for the user to configure a theme more easily,
+without having to write a custom stylesheet, it is necessary to be able to
+template static files as well as HTML files.  Therefore, Sphinx supports
+so-called "static templates", like this:
+
+If the name of a file in the ``static/`` directory of a theme (or in the user's
+static path, for that matter) ends with ``_t``, it will be processed by the
+template engine.  The ``_t`` will be left from the final file name.  For
+example, the *default* theme has a file ``static/default.css_t`` which uses
+templating to put the color options into the stylesheet.  When a documentation
+is built with the default theme, the output directory will contain a
+``_static/default.css`` file where all template tags have been processed.
+
+  
+.. [1] It is not an executable Python file, as opposed to :file:`conf.py`,
+       because that would pose an unnecessary security risk if themes are
+       shared.