provide sections and local TOC for module documentation

hacking/templates/rst.j2

@@ -2,6 +2,13 @@
 
 @{ module }@
 ++++++++++++++++++++++++++++++++++++++
+{% if author %}
+:Author: @{ author }@
+{% endif %}
+
+.. contents::
+   :local:
+   :depth: 1
 
 {# ------------------------------------------
  #
@@ -10,6 +17,9 @@
  #
  --------------------------------------------#}
 
+Synopsis
+--------
+
 {% if version_added is defined -%}
 .. versionadded:: @{ version_added }@
 {% endif %}
@@ -19,6 +29,9 @@
 {% endfor %}
 
 {% if options -%}
+Options
+-------
+
 .. raw:: html
 
     <table border=1 cellpadding=4>
@@ -54,7 +67,10 @@
 {% endfor %}
 {% endif %}
 
-{% if not plainexamples %}
+{% if examples or plainexamples %}
+Examples
+--------
+
 .. raw:: html
 
 {% for example in examples %}
@@ -66,19 +82,18 @@
     </p>
 {% endfor %}
     <br/>
-{% endif %}
 
 {% if plainexamples %}
 
-Examples::
+::
 
 @{ plainexamples | escape | indent(4, True) }@
 {% endif %}
-
+{% endif %}
 
 {% if notes %}
 {% for note in notes %}
-.. note:: @{ note | html_ify }@</p>
+.. note:: @{ note | convert_symbols_to_format }@
 {% endfor %}
 {% endif %}