Added document describing how to generate a static website

docs/static_site_generation.rst

@@ -0,0 +1,83 @@
+Generating a static site
+========================
+
+This document describes how to render your Wagtail site into static HTML files using `django medusa`_ and the 'wagtail.contrib.wagtailmedusa' module.
+
+
+Installing django-medusa
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Firstly, install django medusa from pip:
+
+.. code::
+
+    pip install django-medusa
+
+
+Then add 'django_medusa' and 'wagtail.contrib.wagtailmedusa' to INSTALLED_APPS:
+
+.. code:: python
+
+    INSTALLED_APPS = [
+       ...
+       'django_medusa',
+       'wagtail.contrib.wagtailmedusa',
+    ]
+
+
+Replacing GET parameters with custom routing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Pages which require GET parameters (eg, pagination) don't generate suitable filenames for generated HTML files so they need to be changed to use custom routing instead.
+
+For example, lets say we have a Blog Index which uses pagination. We can override the 'route' method to make it respond on urls like '/page/1' and pass the page number through to the serve method:
+
+.. code:: python
+
+    class BlogIndex(Page):
+        ...
+
+        def serve(self, request, page=1):
+            ...
+
+        def route(self, request, path_components):
+            if self.live and len(path_components) == 2 and path_components[0] == 'page':
+                try:
+                    return self.serve(request, page=int(path_components[1]))
+                except (TypeError, ValueError):
+                    pass
+
+            return super(BlogIndex, self).route(request, path_components)
+
+
+Rendering pages which use custom routing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For page types that override the route method, we need to let django medusa know which URLs it responds on. This is done by overriding the 'get_staticsite_paths' method to make it yield one string per URL path.
+
+For example, the BlogIndex above would need to yield one URL for each page of results:
+
+.. code:: python
+
+    def get_staticsite_paths(self):
+        # Get page count
+        page_count = ...
+
+        # Yield a path for each page
+        for page in range(page_count):
+            yield '/%d/' % (page + 1)
+
+        # Yield from superclass
+        for path in super(BlogIndex, self).get_staticsite_paths():
+            yield path
+
+
+Rendering
+~~~~~~~~~
+
+To render a site, just run ``./manage.py staticsitegen``. This will render the entire website and place the HTML in a folder called 'medusa_output'. The static and media folders need to be copied into this folder manually after the rendering is complete.
+
+To test, open the 'medusa_output' folder in a terminal and run ``python -m SimpleHTTPServer``.
+
+
+.. _django medusa: https://github.com/mtigas/django-medusa