Merge branch 'master' of git://github.com/getpelican/pelican

docs/getting_started.rst

@@ -277,13 +277,12 @@ For RestructuredText, use the code-block directive::
 
        <indented code block goes here>
 
-For Markdown, include the language identifier just above code blocks::
+For Markdown, include the language identifier just above the code block,
+indenting both the identifier and code::
 
         :::identifier
         <code goes here>
 
-    (indent both the identifier and code)
-
 The specified identifier (e.g. ``python``, ``ruby``) should be one that
 appears on the `list of available lexers <http://pygments.org/docs/lexers/>`_.
 

docs/plugins.rst

@@ -76,14 +76,22 @@ request if you need them!
 List of plugins
 ===============
 
-Not all the list are described here, but a few of them have been extracted from
+The following plugins are currently included with Pelican under ``pelican.plugins``:
-the Pelican core and provided in ``pelican.plugins``. They are described here:
 
-Tag cloud
+* `GitHub activity`_
----------
+* `Global license`_
+* `Gravatar`_
+* `HTML tags for reStructuredText`_
+* `Related posts`_
+* `Sitemap`_
 
-Translation
+Ideas for plugins that haven't been written yet:
------------
+
+* Tag cloud
+* Translation
+
+Plugin descriptions
+===================
 
 GitHub activity
 ---------------
@@ -116,23 +124,78 @@ variable, as in the example::
 ``github_activity`` is a list of lists. The first element is the title
 and the second element is the raw HTML from GitHub.
 
+Global license
+--------------
+
+This plugin allows you to define a LICENSE setting and adds the contents of that
+license variable to the article's context, making that variable available to use
+from within your theme's templates.
+
+Gravatar
+--------
+
+This plugin assigns the ``author_gravatar`` variable to the Gravatar URL and
+makes the variable available within the article's context. You can add
+AUTHOR_EMAIL to your settings file to define the default author's email
+address. Obviously, that email address must be associated with a Gravatar
+account.
+
+Alternatively, you can provide an email address from within article metadata::
+
+    :email:  john.doe@example.com
+
+If the email address is defined via at least one of the two methods above,
+the ``author_gravatar`` variable is added to the article's context.
+
+HTML tags for reStructuredText
+------------------------------
+
+This plugin allows you to use HTML tags from within reST documents. Following
+is a usage example, which is in this case a contact form::
+
+    .. html::
+
+        <form method="GET" action="mailto:some email">
+          <p>
+            <input type="text" placeholder="Subject" name="subject">
+            <br />
+            <textarea name="body" placeholder="Message">
+            </textarea>
+            <br />
+            <input type="reset"><input type="submit">
+          </p>
+        </form>
+
+Related posts
+-------------
+
+This plugin adds the ``related_posts`` variable to the article's context.
+To enable, add the following to your settings file::
+
+    from pelican.plugins import related_posts
+    PLUGINS = [related_posts]
+
+You can then use the ``article.related_posts`` variable in your templates.
+For example::
+
+    {% if article.related_posts %}
+        <ul>
+        {% for related_post in article.related_posts %}
+            <li>{{ related_post }}</li>
+        {% endfor %}
+        </ul>
+    {% endif %}
 
 Sitemap
 -------
 
-The plugin generates a sitemap of the blog.
+The sitemap plugin generates plain-text or XML sitemaps. You can use the
-It can generates plain text sitemaps or XML sitemaps.
+``SITEMAP`` variable in your settings file to configure the behavior of the
-
-Configuration
-"""""""""""""
-
-You can use the setting ``SITEMAP`` variable to configure the behavior of the
 plugin.
 
-The ``SITEMAP`` variable must be a Python dictionary, it can contain tree keys:
+The ``SITEMAP`` variable must be a Python dictionary, it can contain three keys:
 
-
+- ``format``, which sets the output format of the plugin (``xml`` or ``txt``)
-- ``format``, which set the output format of the plugin (``xml`` or ``txt``)
 
 - ``priorities``, which is a dictionary with three keys:
 
@@ -154,9 +217,8 @@ The ``SITEMAP`` variable must be a Python dictionary, it can contain tree keys:
 
   - ``indexes``, the update frequency of the index pages
 
-  An valid value is  ``always``, ``hourly``, ``daily``, ``weekly``, ``monthly``,
+  Valid frequency values are ``always``, ``hourly``, ``daily``, ``weekly``, ``monthly``,
-  ``yearly`` or ``never``.
+  ``yearly`` and ``never``.
-
 
 If a key is missing or a value is incorrect, it will be replaced with the
 default value.
@@ -168,11 +230,9 @@ The sitemap is saved in ``<output_path>/sitemap.<format>``.
    They are only used in the XML sitemaps.
    For more information: <http://www.sitemaps.org/protocol.html#xmlTagDefinitions>
 
+**Example**
 
-Example
+Here is an example configuration (it's also the default settings):
-"""""""
-
-Here is an example of configuration (it's also the default settings):
 
 .. code-block:: python
 

docs/settings.rst

@@ -16,6 +16,9 @@ False, None, etc.), dictionaries, or tuples should *not* be enclosed in
 quotation marks. All other values (i.e., strings) *must* be enclosed in
 quotation marks.
 
+Unless otherwise specified, settings that refer to paths can be either absolute or relative to the
+configuration file.
+
 The settings you define in the configuration file will be passed to the
 templates, which allows you to use your settings to add site-wide content.
 
@@ -58,10 +61,10 @@ Setting name (default value)                                            What doe
                                                                         Python-Markdown documentation for a complete list of
                                                                         supported extensions.
 `OUTPUT_PATH` (``'output/'``)                                           Where to output the generated files.
-`PATH` (``None``)                                                       Path to look at for input files.
+`PATH` (``None``)                                                       Path to content directory to be processed by Pelican.
-`PAGE_DIR` (``'pages'``)                                                Directory to look at for pages.
+`PAGE_DIR` (``'pages'``)                                                Directory to look at for pages, relative to `PATH`.
 `PAGE_EXCLUDES` (``()``)                                                A list of directories to exclude when looking for pages.
-`ARTICLE_DIR` (``''``)                                                  Directory to look at for articles.
+`ARTICLE_DIR` (``''``)                                                  Directory to look at for articles, relative to `PATH`.
 `ARTICLE_EXCLUDES`: (``('pages',)``)                                    A list of directories to exclude when looking for articles.
 `PDF_GENERATOR` (``False``)                                             Set to True if you want to have PDF versions
                                                                         of your documents. You will need to install
@@ -373,19 +376,19 @@ Setting name (default value)                        What does it do?
                                                     alphabetical order; default lists alphabetically.)
 ================================================    =====================================================
 
-Theming
+Themes
-=======
+======
 
-Theming is addressed in a dedicated section (see :ref:`theming-pelican`).
+Creating Pelican themes is addressed in a dedicated section (see :ref:`theming-pelican`).
-However, here are the settings that are related to theming.
+However, here are the settings that are related to themes.
 
 ================================================    =====================================================
 Setting name (default value)                        What does it do?
 ================================================    =====================================================
-`THEME`                                             Theme to use to produce the output. Can be the
+`THEME`                                             Theme to use to produce the output. Can be a relative
-                                                    complete static path to a theme folder, or
+                                                    or absolute path to a theme folder, or the name of a
-                                                    chosen between the list of default themes (see
+                                                    default theme or a theme installed via
-                                                    below)
+                                                    ``pelican-themes`` (see below).
 `THEME_STATIC_PATHS` (``['static']``)               Static theme paths you want to copy. Default
                                                     value is `static`, but if your theme has
                                                     other static paths, you can put them here.
@@ -393,22 +396,32 @@ Setting name (default value)                        What does it do?
 `WEBASSETS` (``False``)                             Asset management with `webassets` (see below)
 ================================================    =====================================================
 
-By default, two themes are available. You can specify them using the `-t` option:
+
+By default, two themes are available. You can specify them using the `THEME` setting or by passing the
+``-t`` option to the ``pelican`` command:
 
 * notmyidea
-* simple (a synonym for "full text" :)
+* simple (a synonym for "plain text" :)
-
-You can define your own theme too, and specify its placement in the same
-manner. (Be sure to specify the full absolute path to it.)
-
-Here is :doc:`a guide on how to create your theme <themes>`
-
-You can find a list of themes at http://github.com/getpelican/pelican-themes.
 
+There are a number of other themes available at http://github.com/getpelican/pelican-themes.
 Pelican comes with :doc:`pelican-themes`, a small script for managing themes.
 
-The `notmyidea` theme can make good use of the following settings. I recommend
+You can define your own theme, either by starting from scratch or by duplicating
-using them in your themes as well.
+and modifying a pre-existing theme. Here is :doc:`a guide on how to create your theme <themes>`.
+
+Following are example ways to specify your preferred theme::
+
+    # Specify name of a built-in theme
+    THEME = "notmyidea"
+    # Specify name of a theme installed via the pelican-themes tool
+    THEME = "chunk"
+    # Specify a customized theme, via path relative to the settings file
+    THEME = "themes/mycustomtheme"
+    # Specify a customized theme, via absolute path
+    THEME = "~/projects/mysite/themes/mycustomtheme"
+
+The built-in `notmyidea` theme can make good use of the following settings. Feel
+free to use them in your themes as well.
 
 =======================   =======================================================
 Setting name              What does it do ?
@@ -444,26 +457,27 @@ adding the following to your configuration::
 Asset management
 ----------------
 
-The `WEBASSETS` setting allows to use the `webassets`_ module to manage assets
+The `WEBASSETS` setting allows you to use the `webassets`_ module to manage
-(css, js). The module must first be installed::
+assets such as CSS and JS files. The module must first be installed::
 
     pip install webassets
 
-`webassets` allows to concatenate your assets and to use almost all of the
+The `webassets` module allows you to perform a number of useful asset management
-hype tools of the moment (see the `documentation`_):
+functions, including:
 
-* css minifier (`cssmin`, `yuicompressor`, ...)
+* CSS minifier (`cssmin`, `yuicompressor`, ...)
-* css compiler (`less`, `sass`, ...)
+* CSS compiler (`less`, `sass`, ...)
-* js minifier (`uglifyjs`, `yuicompressor`, `closure`, ...)
+* JS minifier (`uglifyjs`, `yuicompressor`, `closure`, ...)
 
-Others filters include gzip compression, integration of images in css with
+Others filters include gzip compression, integration of images in CSS via data
-`datauri` and more. Webassets also append a version identifier to your asset
+URIs, and more. `webassets` can also append a version identifier to your asset
-url to convince browsers to download new versions of your assets when you use
+URL to convince browsers to download new versions of your assets when you use
-far future expires headers.
+far-future expires headers. Please refer to the `webassets documentation`_ for
+more information.
 
-When using it with Pelican, `webassets` is configured to process assets in the
+When using with Pelican, `webassets` is configured to process assets in the
-``OUTPUT_PATH/theme`` directory. You can use it in your templates with a
+``OUTPUT_PATH/theme`` directory. You can use `webassets` in your templates by
-template tag, for example:
+including one or more template tags. For example...
 
 .. code-block:: jinja
 
@@ -471,22 +485,22 @@ template tag, for example:
         <link rel="stylesheet" href="{{ ASSET_URL }}">
     {% endassets %}
 
-will produce a minified css file with the version identifier:
+... will produce a minified css file with a version identifier:
 
 .. code-block:: html
 
     <link href="http://{SITEURL}/theme/css/style.min.css?b3a7c807" rel="stylesheet">
 
-The filters can be combined, for example to use the `sass` compiler and minify
+These filters can be combined. Here is an example that uses the SASS compiler
-the output::
+and minifies the output:
 
 .. code-block:: jinja
 
-{% assets filters="sass,cssmin", output="css/style.min.css", "css/style.scss" %}
+    {% assets filters="sass,cssmin", output="css/style.min.css", "css/style.scss" %}
-    <link rel="stylesheet" href="{{ ASSET_URL }}">
+        <link rel="stylesheet" href="{{ ASSET_URL }}">
-{% endassets %}
+    {% endassets %}
 
-Another example for javascript:
+Another example for Javascript:
 
 .. code-block:: jinja
 
@@ -494,20 +508,20 @@ Another example for javascript:
         <script src="{{ ASSETS_URL }}"></script>
     {% endassets %}
 
-will produce a minified and gzipped js file:
+The above will produce a minified and gzipped JS file:
 
 .. code-block:: html
 
     <script src="http://{SITEURL}/theme/js/packed.js?00703b9d"></script>
 
-Pelican's debug mode is propagated to webassets to disable asset packaging,
+Pelican's debug mode is propagated to `webassets` to disable asset packaging
 and instead work with the uncompressed assets. However, this also means that
-the `less` and `sass` files are not compiled, this should be fixed in a future
+the LESS and SASS files are not compiled. This should be fixed in a future
-version of webassets (cf. the related `bug report
+version of `webassets` (cf. the related `bug report
 <https://github.com/getpelican/pelican/issues/481>`_).
 
 .. _webassets: https://github.com/miracle2k/webassets
-.. _documentation: http://webassets.readthedocs.org/en/latest/builtin_filters.html
+.. _webassets documentation: http://webassets.readthedocs.org/en/latest/builtin_filters.html
 
 Example settings
 ================

pelican/generators.py

@@ -378,7 +378,7 @@ class PagesGenerator(Generator):
                 os.path.join(self.path, self.settings['PAGE_DIR']),
                 exclude=self.settings['PAGE_EXCLUDES']):
             try:
-                content, metadata = read_file(f)
+                content, metadata = read_file(f, settings=self.settings)
             except Exception, e:
                 logger.warning(u'Could not process %s\n%s' % (f, str(e)))
                 continue

pelican/plugins/global_license.py

@@ -4,13 +4,14 @@ from pelican import signals
 License plugin for Pelican
 ==========================
 
-Simply add license variable in article's context, which contain 
+This plugin allows you to define a LICENSE setting and adds the contents of that
-the license text.
+license variable to the article's context, making that variable available to use
+from within your theme's templates.
 
 Settings:
 ---------
 
-Add LICENSE to your settings file to define default license.
+Define LICENSE in your settings file with the contents of your default license.
 
 """
 

pelican/plugins/gravatar.py

@@ -5,20 +5,22 @@ from pelican import signals
 Gravatar plugin for Pelican
 ===========================
 
-Simply add author_gravatar variable in article's context, which contains
+This plugin assigns the ``author_gravatar`` variable to the Gravatar URL and
-the gravatar url.
+makes the variable available within the article's context.
 
 Settings:
 ---------
 
-Add AUTHOR_EMAIL to your settings file to define default author email.
+Add AUTHOR_EMAIL to your settings file to define the default author's email
+address. Obviously, that email address must be associated with a Gravatar
+account.
 
 Article metadata:
 ------------------
 
 :email:  article's author email
 
-If one of them are defined, the author_gravatar variable is added to
+If one of them are defined, the author_gravatar variable is added to the
 article's context.
 """