Improve ical plugin documentation

ical/Readme.rst

@@ -1,28 +1,39 @@
 ical
---------
+----
 
-This plugin read the calendar defined in the page metadata : calendar :
+This plugin looks for and parses an ``.ics`` file if it is defined in a given
+page's ``calendar`` metadata. One calendar can be defined per page.
 
-with::
+Dependencies
+------------
+
+This plugin depends on the ``icalendar`` package, which can be installed via
+pip::
+
+	pip install icalendar
+
+Usage
+-----
+
+For a reST-formatted page, include the following line in the metadata::
 
     :calendar: /path/to/your/ics/file
 
-Example of code that can be added in page template ::
+For Markdown, include the following line in the page metadata::
 
+    Calendar: /path/to/your/ics/file
+
+Following is some example code that can be added to your theme's ``page.html``
+template in order to display the calendar::
 
     {% if page.calendar %}
     <dl>
-        {% for vevent in  events[page.slug] %}
+        {% for vevent in events[page.slug] %}
             <dt>{{ vevent.summary }}</dt>
             <dd>{{ vevent.description|replace('\n\n', '<br>') }}</dd>
             <dd>{{ vevent.dtstart }}</dd>
             <dd>{{ vevent.dtend }}</dd>
-            <dd class="footer"><a href="{{ vevent.url }}" target="_blank">See more</a></dd>
+            <dd class="footer"><a href="{{ vevent.url }}">See more</a></dd>
         {% endfor %}
     </dl>
     {% endif %}
-    
-this plugins needs icalendar module installed::
-
-	pip install icalendar
-

ical/ical.py

@@ -1,10 +1,10 @@
 # -*- coding: utf-8 -*-
 """
 ical plugin for Pelican
-===========================
+=======================
 
-This plugin parse the calendars defined in pages metadata :calendar:
+This plugin looks for and parses an .ics file if it is defined in a given
-One calendar per page
+page's :calendar: metadata. One calendar can be defined per page.
 
 """
 
@@ -15,7 +15,7 @@ import datetime
 import os.path
 
 def init_cal(generator):
-    # initialisation of the dictionnary of calendar 
+    # initialisation of the calendar dictionary
     # you can add one calendar per page
     calDict = {}
     generator.context['events'] = calDict
@@ -42,7 +42,7 @@ def add_ical(generator, metadata):
                 if element.get('dtend') != None:
                     eventdict['dtend'] = element.get('dtend').dt
                 summ.append(eventdict)
-        # the id of the calendar is the slugify name of the page
+        # the id of the calendar is the slugified name of the page
         calId = utils.slugify(metadata['title'])
         generator.context['events'][calId] = summ