Add a list of plugins to the docs. Closes #493.

docs/plugins.rst

@@ -72,14 +72,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
 ---------------
@@ -112,23 +120,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:
 
@@ -150,9 +213,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.
@@ -164,11 +226,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
 

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.
 """