Add a documentation about themes.

README.rst

@@ -106,13 +106,21 @@ Setting name              what it does ?
                           metadata?
 `MARKUP`                  A list of available markup languages you want to use.
                           moment, only available values are `rst` and `md`.
-`STATIC_PATHS`            The static paths you want to copy under "static"
-`FEED`                    relative url to output the feed. Default is
+`STATIC_PATHS`            The static paths you want to have accessible on the
+                          output path "static". By default, pelican will copy
+                          the 'images' folder to the output folder.
+`STATIC_THEME_PATHS`      Static theme paths you want to copy. Default values
+                          is `static`, but if your theme have others static paths,
+                          you can put them here.
+`FEED`                    relative url to output the atom feed. Default is
                           `feeds/all.atom.xml`
-`FEED_RSS`                relative url to output the rss feed. Default is None (no rss)
-`CATEGORY_FEED`           Where to put the categories feeds. default is 
-                          `feeds/%s.atom.xml`
-`CATEGORY_FEED_RSS`       Where to put the categories rss feeds. default is None (no rss)
+`FEED_RSS`                relative url to output the rss feed. Default is
+                          None (no rss)
+`CATEGORY_FEED`           Where to put the atom categories feeds. default is
+                          `feeds/%s.atom.xml`, where %s is the name of the
+                          category.
+`CATEGORY_FEED_RSS`       Where to put the categories rss feeds. default is None
+                          (no rss)
 `CSS_FILE`                To specify the CSS file you want to load, if it's not
                           the default one ('main.css')
 =======================   =======================================================
@@ -129,6 +137,9 @@ Themes
 You can define your own theme too, and specify it's emplacement in the same
 way (be sure to specify the full absolute path to it).
 
+Here is `a guide on how to create your theme
+<http://alexis.notmyidea.org/pelican/themes.html>`_
+
 The `notmyidea` theme can make good use of the following settings. I recommend
 to use them too in your themes.
 

docs/themes.rst

@@ -0,0 +1,90 @@
+How to create themes for pelican
+################################
+
+Pelican uses the great `jinja2 <http://jinjna.pocoo.org>`_ templating engine to
+generate it's HTML output.
+
+Structure
+=========
+
+To make your own theme, you must follow the following structure::
+
+    ├── static
+    │   ├── css
+    │   └── images
+    └── templates
+        ├── archives.html
+        ├── article.html
+        ├── categories.html
+        ├── category.html
+        ├── index.html
+        ├── page.html
+        ├── tag.html
+        └── tags.html
+
+* `static` contains all the static content. It will be copied on the output
+  `theme/static` folder then. I've put the css and image folders, but they are
+  just examples. Put what you need here.
+
+* `templates` contains all the templates that will be used to generate the content.
+  I've just put the mandatory templates here, you can define your own if it helps 
+  you to organize yourself while doing the theme.
+ 
+Templates and variables
+=======================
+
+It's using a simple syntax, that you can embbed into your html pages.
+This document describes which templates should exists on a theme, and which
+variables will be passed to each template, while generating it.
+
+All templates will receive the variables defined in your settings file, if they 
+are in caps. You can access them directly. 
+
+Common variables
+----------------
+
+=============   ===================================================
+Variable        Description
+=============   ===================================================
+articles        That's the list of articles, ordsered desc. by date
+                all the elements are `Article` objects, so you can 
+                access their properties (e.g. title, summary, author
+                etc. 
+dates           The same list of article, but ordered by date,
+                ascending
+tags            A dict containing each tags (keys), and the list of
+                relative articles.
+categories      A dict containing each category (keys), and the 
+                list of relative articles.
+pages           The list of pages
+=============   ===================================================
+
+category.html
+-------------
+
+=============   ===================================================
+Variable        Description
+=============   ===================================================
+articles        The articles of this category
+category        The name of the category being processed
+=============   ===================================================
+
+article.html
+-------------
+
+=============   ===================================================
+Variable        Description
+=============   ===================================================
+article         The article object to be displayed
+category        The name of the category of the current article
+=============   ===================================================
+
+tag.html
+--------
+
+=============   ===================================================
+Variable        Description
+=============   ===================================================
+tag             The name of the tag being processed
+articles        Articles related to this tag
+=============   ===================================================

pelican/generators.py

@@ -110,8 +110,9 @@ class ArticlesGenerator(Generator):
         for template in _DIRECT_TEMPLATES:
             write('%s.html' % template, templates[template], self.context,
                     blog=True)
-        for tag in self.tags:
-            write('tag/%s.html' % tag, templates['tag'], self.context, tag=tag)
+        for tag, articles in self.tags.items():
+            write('tag/%s.html' % tag, templates['tag'], self.context, tag=tag, 
+                    articles=articles)
         for cat in self.categories:
             write('category/%s.html' % cat, templates['category'], self.context,
                           category=cat, articles=self.categories[cat])
@@ -193,7 +194,8 @@ class PagesGenerator(Generator):
 
 
 class StaticGenerator(Generator):
-    """copy static paths to output"""
+    """copy static paths (what you want to cpy, like images, medias etc.
+    to output"""
 
     def _copy_paths(self, paths, source, destination, output_path,
             final_path=None):
@@ -204,7 +206,7 @@ class StaticGenerator(Generator):
     def generate_output(self, writer):
         self._copy_paths(self.settings['STATIC_PATHS'], self.path,
                          'static', self.output_path)
-        self._copy_paths(self.settings['THEME_PATHS'], self.theme,
+        self._copy_paths(self.settings['THEME_STATIC_PATHS'], self.theme,
                          'theme', self.output_path, '.')
 
 

pelican/settings.py

@@ -7,7 +7,7 @@ _DEFAULT_CONFIG = {'PATH': None,
                    'OUTPUT_PATH': 'output/',
                    'MARKUP': ('rst', 'md'),
                    'STATIC_PATHS': ['images',],
-                   'THEME_PATHS': ['static',],
+                   'THEME_STATIC_PATHS': ['static',],
                    'FEED': 'feeds/all.atom.xml',
                    'CATEGORY_FEED': 'feeds/%s.atom.xml',
                    'SITENAME': 'A Pelican Blog',