Add a documentation about themes.

README.rst

@@ -36,8 +36,8 @@ You can also use a markdown syntax (with a file ending in `.md`)::
     Put you content here.
 
 Note that none of those are mandatory: if the date is not specified, pelican will
-rely on the mtime of your file, and the category can also be determined by the 
-directory where the rst file is. For instance, the category of 
+rely on the mtime of your file, and the category can also be determined by the
+directory where the rst file is. For instance, the category of
 `python/foobar/myfoobar.rst` is `foobar`.
 
 Features
@@ -46,16 +46,16 @@ Features
 Pelican currently supports:
 
 * blog articles
-* comments, via an external service (disqus). Please notice that while 
-  it's useful, it's an external service, and you'll not manage the 
+* comments, via an external service (disqus). Please notice that while
+  it's useful, it's an external service, and you'll not manage the
   comments by yourself. It could potentially eat your data.
 * theming support (themes are done using `jinja2 <http://jinjna.pocoo.org>`_)
 * PDF generation of the articles/pages (optional).
 
 Getting started — Generate your blog
 -------------------------------------
 
-You're ready? Let's go ! You can install pelican in a lot of different ways, 
+You're ready? Let's go ! You can install pelican in a lot of different ways,
 the simpler one is via `pip <http://pip.openplans.org/>`_::
 
     $ pip install pelican
@@ -67,7 +67,7 @@ Then, you have just to launch pelican, like this::
 And… that's all! You can see your weblog generated on the `content/` folder.
 
 This one will just generate a simple output, with the default theme. It's not
-really sexy, as it's a simple HTML output (without any style). 
+really sexy, as it's a simple HTML output (without any style).
 
 You can create your own style if you want, have a look to the help to see all
 the options you can use::
@@ -82,7 +82,7 @@ the command line::
 
     $ pelican -s path/to/your/settingsfile.py path
 
-Here are the available settings. Please note that all the settings you put in 
+Here are the available settings. Please note that all the settings you put in
 this file will be passed to the templates as well.
 
 =======================   =======================================================
@@ -96,7 +96,7 @@ Setting name              what it does ?
 `OUTPUT_PATH`             Where to output the generated files. Default to
                           "output"
 `SITENAME`                Your site name,
-`DISPLAY_PAGES_ON_MENU`   Display or not the pages on the menu of the template. 
+`DISPLAY_PAGES_ON_MENU`   Display or not the pages on the menu of the template.
                           Templates can follow or not this settings.
 `PDF_PROCESSOR`           Put True if you want to have PDF versions of your
                           documents. You will need to install `rst2pdf`.
@@ -106,14 +106,22 @@ 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)
-`CSS_FILE`                To specify the CSS file you want to load, if it's not 
+`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')
 =======================   =======================================================
 
@@ -124,11 +132,14 @@ Themes
 
 * notmyidea
 * simple (a synonym for "full text" :)
-* martyalchin 
+* martyalchin
 
 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.
 
@@ -142,7 +153,7 @@ Setting name              what it does ?
 `LINKS`                   A list of tuples (Title, Url) for links to appear on
                           the header.
 `SOCIAL`                  A list of tuples (Title, Url) to appear in the "social"
-                          section. 
+                          section.
 `GOOGLE_ANALYTICS`        'UA-XXXX-YYYY' to activate google analytics.
 =======================   =======================================================
 

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 @@ def generate_pages(self, writer):
         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 @@ def generate_output(self, writer):
 
 
 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 @@ def _copy_paths(self, paths, source, destination, output_path,
     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 @@
                    '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',