First work on theming docs and example

ckanext/example_theme/plugin.py

@@ -0,0 +1,9 @@
+import ckan.plugins as plugins
+
+
+class ExampleThemePlugin(plugins.SingletonPlugin):
+    '''An example plugin that just registers the directories containing our
+    example theme files.
+
+    '''
+    pass

doc/theming.rst

@@ -2,12 +2,159 @@
 Theming
 =======
 
-If you want more control over your CKAN site's layout and appearance than the
-options described in :doc:`getting-started` give, you can further customize
-CKAN's appearance by developing a theme. CKAN's templates, HTML and CSS are all
-completely customizable by themes. This document will walk you through the
-process of developing a CKAN theme.
+.. todo::
 
+   Add more to :doc:`getting-started`, is there more that can be done in the
+   config file, e.g. site logo?
+
+:doc:`getting-started` documents some simple CKAN configuration settings that
+you can use to, for example, change the title of your CKAN site. For those who
+want more control over their CKAN site's frontend, this document covers
+everything you need to know to develop a custom CKAN theme, including how to
+customize CKAN's HTML templates, CSS and |javascript|. The sections below will
+walk you through the process of creating a simple, example CKAN theme that
+demonstrates all of the main features of CKAN theming.
+
+.. todo::
+
+   Insert link to the completed example theme here.
+
+
+---------------
+Installing CKAN
+---------------
+
+Before you can start developing a CKAN theme, you’ll need a working source
+install of CKAN on your system. If you don’t have a CKAN source install
+already, follow the instructions in :doc:`install-from-source` before
+continuing.
+
+
+-------------------------
+Creating a CKAN extension
+-------------------------
+
+A CKAN theme must be contained within a CKAN extension, so we'll begin by
+creating an extension to hold our theme. As documented in
+:doc:`writing-extensions`, extensions can customize and extend CKAN's features
+in many powerful ways, but in this example we'll use our extension only to hold
+our theme.
+
+.. todo::
+
+   This stuff is duplicated from the writing extensions docs, do a Sphinx
+   include here instead.
+
+First, use the ``paster create`` command to create an empty extension:
+
+.. parsed-literal::
+
+   |activate|
+   cd |virtualenv|/src
+   paster --plugin=ckan create -t ckanext ckanext-example_theme
+
+The command will ask you to answer a few questions. The answers you give will
+end up in your extension's ``setup.py`` file (where you can edit them later if
+you want).
+
+(See :doc:`writing-extensions` for full documentation on creating CKAN
+extensions and plugins.)
+
+Now create the file ``ckanext-example_theme/ckanext/example_theme/plugin.py``
+with the following contents:
+
+.. literalinclude:: ../ckanext/example_theme/plugin.py
+
+Now let's add our plugin to the ``entry_points`` in ``setup.py``.  This
+identifies the plugin to CKAN once the extension is installed in CKAN's
+virtualenv. Edit ``ckanext-example_theme/setup.py`` and add a line to the
+``entry_points`` section like this::
+
+    entry_points='''
+        [ckan.plugins]
+        example_theme=ckanext.example_theme.plugin:ExampleThemePlugin
+    ''',
+
+Install the ``example_theme`` extension:
+
+.. parsed-literal::
+
+   |activate|
+   cd |virtualenv|/src/ckanext-example_theme
+   python setup.py develop
+
+Finally, enable the plugin in your CKAN config file. Edit |development.ini| and
+add ``example_theme`` to the ``ckan.plugins`` line, for example::
+
+    ckan.plugins = stats text_preview recline_preview example_theme
+
+You should now be able to start CKAN in the development web server and have it
+start up without any problems:
+
+.. parsed-literal::
+
+    $ paster serve |development.ini|
+    Starting server in PID 13961.
+    serving on 0.0.0.0:5000 view at http://127.0.0.1:5000
+
+If your plugin is in the :ref:`ckan.plugins` setting and CKAN starts without
+crashing, then your plugin is installed and CKAN can find it. Of course, your
+plugin doesn't *do* anything yet.
+
+
+--------------------------------------------
+Customizing CKAN's HTML and Jinja2 templates
+--------------------------------------------
+
+.. todo::
+
+   * Introduce Bootstrap here. A lot of Bootstrap stuff can be done just using
+     HTML. It should also get mentioned in other sections (CSS, JavaScript..)
+   * HTML (which version?)
+   * Jinja2
+   * CKAN's custom Jinja2 tags and form macros
+
+
+---------------------------------------------------------------------
+Adding CSS, JavaScript, images and other static files using Fanstatic
+---------------------------------------------------------------------
+
+.. todo::
+
+   * Introduce Fanstatic
+   * Use the plugin to register a Fanstatic library
+   * Use ``{% resource %}`` to load stuff from the library
+   * Presumably you can also load stuff from the core library?
+
+
+----------------------
+Customizing CKAN's CSS
+----------------------
+
+.. todo::
+
+   * Introduce CSS?
+   * Use Fanstatic to add a CSS file
+   * Use Bootstrap's CSS files and CKAN core's
+   * See the CKAN style guide
+
+
+-----------------------------
+Customizing CKAN's JavaScript
+-----------------------------
+
+.. todo::
+
+   * How to load JavaScript modules
+   * jQuery
+   * Bootstrap's JavaScript stuff
+   * Other stuff in javascript-module-tutorial.rst
+
+
+
+
+
+----
 
 Create Custom Extension
 -----------------------

setup.py

@@ -122,6 +122,7 @@
     recline_preview=ckanext.reclinepreview.plugin:ReclinePreview
     example_itemplatehelpers=ckanext.example_itemplatehelpers.plugin:ExampleITemplateHelpersPlugin
     example_idatasetform=ckanext.example_idatasetform.plugin:ExampleIDatasetFormPlugin
+    example_theme=ckanext.example_theme.plugin:ExampleThemePlugin
 
     [ckan.system_plugins]
     domain_object_mods = ckan.model.modification:DomainObjectModificationExtension