Fix: rst - wrong handling of initial lonely heading

docs/content/docs/config.mkd

@@ -31,6 +31,10 @@ are:
 - `relative_urls` (false) - If this option is turned on, then any urls
   generated will not include a leading '/'. If this is false, all urls
   generated will include a leading '/'.
+- `rst_doctitle` (false) - Disable rst/docutils' promotion of a lone top-level
+  section title to document title (was enabled up to wok 1.1.1 - by mistake).
+  Might be optionally enabled here (or on per page basis) again - for backwards
+  compatibility.
 
 [content]: /docs/content/
 [URLs]: /docs/urls/

docs/content/docs/content.mkd

@@ -57,6 +57,9 @@ pages in the YAML metadata.
     configuration file will be used. ([More about managing URLs][URLs])
 -   `pagination` - An object who's presence will trigger paginating this page.
     See [pagination][] for more details.
+-   `rst_doctitle` - Re-enable rst/docutils' promotion of a lone top-level
+    section title to document title.
+    (Only for backwards compatibility - was enabled up to wok 1.1.1 - a bug?)
 
 [8601]: http://en.wikipedia.org/wiki/ISO_8601
 [URLs]: /docs/urls/

test_site/renderers/__renderers__.py

@@ -2,14 +2,14 @@
 
 try:
     from bs4 import BeautifulSoup
-    def render(plain):
+    def render(plain, page_meta):
         soup = BeautifulSoup(plain)
         return soup.body
 
 except ImportError:
     import cgi
     logging.warning('HTML rendering relies on the BeautifulSoup library.')
-    def render(plain):
+    def render(plain, page_meta):
         return '<h1>Rendering error</h1>' \
             + '<p><code>BeautifulSoup</code> could not be loaded.</p>' \
             + '<p>Original plain document follows:</p>' \

wok/engine.py

@@ -35,6 +35,7 @@ class Engine(object):
         'locale': None,
         'markdown_extra_plugins': [],
         'ignore_files': [],
+        'rst_doctitle': False,
     }
     SITE_ROOT = os.getcwd()
 
@@ -247,6 +248,12 @@ def renderer_options(self):
         if hasattr(renderers, 'Markdown2'):
             renderers.Markdown2.extras.extend(markdown_extra_plugins)
 
+        # reStructuredText options
+        if hasattr(renderers, 'ReStructuredText'):
+            renderers.ReStructuredText.options.update( \
+                {'doctitle' : self.options.get('rst_doctitle', False), \
+                })
+
     def sanity_check(self):
         """Basic sanity checks."""
         # Make sure that this is (probabably) a wok source directory.

wok/page.py

@@ -117,8 +117,8 @@ def from_file(cls, path, options, engine, renderer=renderers.Plain):
         page.build_meta()
 
         page.engine.run_hook('page.render.pre', page)
-        page.meta['content'] = page.renderer.render(page.original)
-        page.meta['preview'] = page.renderer.render(page.original_preview)
+        page.meta['content'] = page.renderer.render(page.original, page.meta)  # the page.meta might contain renderer options...
+        page.meta['preview'] = page.renderer.render(page.original_preview, page.meta)
         page.engine.run_hook('page.render.post', page)
 
         return page

wok/renderers.py

@@ -16,7 +16,7 @@ class Renderer(object):
     extensions = []
 
     @classmethod
-    def render(cls, plain):
+    def render(cls, plain, page_meta):   # the page_meta might contain renderer options...
         return plain
 all.append(Renderer)
 
@@ -25,7 +25,7 @@ class Plain(Renderer):
     extensions = ['txt']
 
     @classmethod
-    def render(cls, plain):
+    def render(cls, plain, page_meta):
         return plain.replace('\n', '<br>')
 all.append(Plain)
 
@@ -42,7 +42,7 @@ class Markdown(Renderer):
             plugins.extend(['codehilite(css_class=codehilite)', 'fenced_code'])
 
         @classmethod
-        def render(cls, plain):
+        def render(cls, plain, page_meta):
             return markdown(plain, cls.plugins)
 
     all.append(Markdown)
@@ -64,7 +64,7 @@ class Markdown2(Renderer):
                 extras.append('fenced-code-blocks')
 
             @classmethod
-            def render(cls, plain):
+            def render(cls, plain, page_meta):
                 return markdown2.markdown(plain, extras=cls.extras)
 
         all.append(Markdown2)
@@ -85,11 +85,23 @@ def render(cls, plain):
     class ReStructuredText(Renderer):
         """reStructuredText renderer."""
         extensions = ['rst']
+        options = {}
 
         @classmethod
-        def render(cls, plain):
+        def render(cls, plain, page_meta):
             w = rst_html_writer()
-            return docutils.core.publish_parts(plain, writer=w)['body']
+            #return docutils.core.publish_parts(plain, writer=w)['body']
+            # Problem: missing heading and/or title if it's a lone heading
+            #
+            # Solution:
+            #     Disable the promotion of a lone top-level section title to document title
+            #     (and subsequent section title to document subtitle promotion)
+            #
+            #      http://docutils.sourceforge.net/docs/api/publisher.html#id3
+            #      http://docutils.sourceforge.net/docs/user/config.html#doctitle-xform
+            #
+            overrides = { 'doctitle_xform': page_meta.get('rst_doctitle', cls.options['doctitle']), }
+            return docutils.core.publish_parts(plain, writer=w, settings_overrides=overrides)['body']
 
     all.append(ReStructuredText)
 except ImportError:
@@ -104,7 +116,7 @@ class Textile(Renderer):
         extensions = ['textile']
 
         @classmethod
-        def render(cls, plain):
+        def render(cls, plain, page_meta):
             return textile.textile(plain)
 
     all.append(Textile)