merged master, ongoing styling

.travis.yml

@@ -14,7 +14,7 @@ services:
 # Package installation
 install:
   - python setup.py install
-  - pip install psycopg2 elasticsearch wand embedly
+  - pip install psycopg2 elasticsearch wand embedly mock python-dateutil
   - pip install coveralls
 # Pre-test configuration
 before_script:

CHANGELOG.txt

@@ -1,9 +1,26 @@
 Changelog
 =========
 
-0.5 (xx.xx.20xx)
+0.6 (xx.xx.20xx)
 ~~~~~~~~~~~~~~~~
+ * Added {% routablepageurl %} template tag (@timheap)
+ * Added RoutablePageMixin (@timheap)
+ * Fix: Page URL generation now returns correct URLs for sites that have the main 'serve' view rooted somewhere other than '/'
+
+0.5 (01.08.2014)
+~~~~~~~~~~~~~~~~
+ * Added multiple image uploader
+ * Added support for face and feature detection on images using the OpenCV library
+ * Added RoutablePage model to allow embedding Django-style URL routing within a page
+ * Added image/document/snippet usage stats
+ * Explorer nav now rendered separately and fetched with AJAX when needed
  * Added decorator syntax for hooks
+ * Replaced lxml dependency with html5lib, to simplify installation
+ * Added page_unpublished signal
+ * Added mechanism to obtain external URLs to images, at any size
+ * Added Copy Page action to the explorer
+
+ * Fix: Updates to tag fields are now properly committed to the database when publishing directly from the page edit interface
 
 0.4.1 (14.07.2014)
 ~~~~~~~~~~~~~~~~~~

CONTRIBUTORS.rst

@@ -30,6 +30,7 @@ Contributors
 * Jeffrey Hearn
 * Robert Clark
 * Tim Heap
+* Nathan Brizendine
 
 Translators
 ===========

README.rst

@@ -24,8 +24,8 @@ Wagtail is a Django content management system built originally for the `Royal Co
 * Support for tree-based content organisation
 * Optional preview->submit->approve workflow
 * Fast out of the box. `Varnish <https://www.varnish-cache.org/>`_-friendly if you need it
-* A simple `form builder <http://docs.wagtail.io/en/latest/form_builder.html>`_
-* Optional `static site generation <http://docs.wagtail.io/en/latest/static_site_generation.html>`_
+* A simple `form builder <file:///home/karl/projects/wagtaildemo/wagtail/docs/_build/html/core_components/form_builder.html>`_
+* Optional `static site generation <http://docs.wagtail.io/en/latest/contrib_components/static_site_generation.html>`_
 * Excellent `test coverage <https://coveralls.io/r/torchbox/wagtail?branch=master>`_
 
 Find out more at `wagtail.io <http://wagtail.io/>`_.

docs/advanced_topics.rst

@@ -1,17 +0,0 @@
-Advanced Topics
-~~~~~~~~~~~~~~~~
-
-.. note::
-    This documentation is currently being written.
-
-replacing image processing backend
-
-custom image processing tags?
-
-wagtail user bar custom CSS option?
-
-extending hallo editor plugins with editor_js()
-
-injecting any JS into page edit with editor_js()
-
-Custom content module (same level as docs or images)

docs/building_your_site/djangodevelopers.rst

@@ -1,428 +0,0 @@
-For Django developers
-=====================
-
-.. contents:: Contents
-    :local:
-
-.. note::
-    This documentation is currently being written.
-
-Overview
-~~~~~~~~
-
-Wagtail requires a little careful setup to define the types of content that you want to present through your website. The basic unit of content in Wagtail is the ``Page``, and all of your page-level content will inherit basic webpage-related properties from it. But for the most part, you will be defining content yourself, through the construction of Django models using Wagtail's ``Page`` as a base.
-
-Wagtail organizes content created from your models in a tree, which can have any structure and combination of model objects in it. Wagtail doesn't prescribe ways to organize and interrelate your content, but here we've sketched out some strategies for organizing your models.
-
-The presentation of your content, the actual webpages, includes the normal use of the Django template system. We'll cover additional functionality that Wagtail provides at the template level later on.
-
-But first, we'll take a look at the ``Page`` class and model definitions.
-
-
-The Page Class
-~~~~~~~~~~~~~~
-
-``Page`` uses Django's model interface, so you can include any field type and field options that Django allows. Wagtail provides some fields and editing handlers that simplify data entry in the Wagtail admin interface, so you may want to keep those in mind when deciding what properties to add to your models in addition to those already provided by ``Page``.
-
-
-Built-in Properties of the Page Class
--------------------------------------
-
-Wagtail provides some properties in the ``Page`` class which are common to most webpages. Since you'll be subclassing ``Page``, you don't have to worry about implementing them.
-
-Public Properties
-`````````````````
-
-    ``title`` (string, required)
-        Human-readable title for the content
-
-    ``slug`` (string, required)
-        Machine-readable URL component for this piece of content. The name of the page as it will appear in URLs e.g ``http://domain.com/blog/[my-slug]/``
-
-    ``seo_title`` (string)
-        Alternate SEO-crafted title which overrides the normal title for use in the ``<head>`` of a page
-
-    ``search_description`` (string)
-        A SEO-crafted description of the content, used in both internal search indexing and for the meta description read by search engines
-
-The ``Page`` class actually has alot more to it, but these are probably the only built-in properties you'll need to worry about when creating templates for your models.
-
-
-Anatomy of a Wagtail Model
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-So what does a Wagtail model definition look like? Here's a model representing a typical blog post:
-
-.. code-block:: python
-
-    from django.db import models
-
-    from wagtail.wagtailcore.models import Page
-    from wagtail.wagtailcore.fields import RichTextField
-    from wagtail.wagtailadmin.edit_handlers import FieldPanel
-    from wagtail.wagtailimages.edit_handlers import ImageChooserPanel
-    from wagtail.wagtailimages.models import Image
-
-    class BlogPage(Page):
-        body = RichTextField()
-        date = models.DateField("Post date")
-        feed_image = models.ForeignKey(
-            'wagtailimages.Image',
-            null=True,
-            blank=True,
-            on_delete=models.SET_NULL,
-            related_name='+'
-        )
-
-    BlogPage.content_panels = [
-        FieldPanel('title', classname="full title"),
-        FieldPanel('date'),
-        FieldPanel('body', classname="full"),
-    ]
-
-    BlogPage.promote_panels = [
-        FieldPanel('slug'),
-        FieldPanel('seo_title'),
-        FieldPanel('show_in_menus'),
-        FieldPanel('search_description'),
-        ImageChooserPanel('feed_image'),
-    ]
-
-To keep track of your ``Page``-derived models, it might be helpful to include "Page" as the last part of your class name. ``BlogPage`` defines three properties: ``body``, ``date``, and ``feed_image``. These are a mix of basic Django models (``DateField``), Wagtail fields (``RichTextField``), and a pointer to a Wagtail model (``Image``).
-
-Next, the ``content_panels`` and ``promote_panels`` lists define the capabilities and layout of the Wagtail admin page edit interface. The lists are filled with "panels" and "choosers", which will provide a fine-grain interface for inputting the model's content. The ``ImageChooserPanel``, for instance, lets one browse the image library, upload new images, and input image metadata. The ``RichTextField`` is the basic field for creating web-ready website rich text, including text formatting and embedded media like images and video. The Wagtail admin offers other choices for fields, Panels, and Choosers, with the option of creating your own to precisely fit your content without workarounds or other compromises.
-
-Your models may be even more complex, with methods overriding the built-in functionality of the ``Page`` to achieve webdev magic. Or, you can keep your models simple and let Wagtail's built-in functionality do the work.
-
-Now that we have a basic idea of how our content is defined, lets look at relationships between pieces of content.
-
-
-Introduction to Trees
-~~~~~~~~~~~~~~~~~~~~~
-
-If you're unfamiliar with trees as an abstract data type, you might want to `review the concepts involved. <http://en.wikipedia.org/wiki/Tree_(data_structure)>`_
-
-As a web developer, though, you probably already have a good understanding of trees as filesystem directories or paths. Wagtail pages can create the same structure, as each page in the tree has its own URL path, like so::
-
-    /
-        people/
-            nien-nunb/
-            laura-roslin/
-        events/
-            captain-picard-day/
-            winter-wrap-up/
-
-The Wagtail admin interface uses the tree to organize content for editing, letting you navigate up and down levels in the tree through its Explorer menu. This method of organization is a good place to start in thinking about your own Wagtail models.
-
-
-Nodes and Leaves
-----------------
-
-It might be handy to think of the ``Page``-derived models you want to create as being one of two node types: parents and leaves. Wagtail isn't prescriptive in this approach, but it's a good place to start if you're not experienced in structuring your own content types.
-
-
-Nodes
-`````
-Parent nodes on the Wagtail tree probably want to organize and display a browse-able index of their descendants. A blog, for instance, needs a way to show a list of individual posts.
-
-A Parent node could provide its own function returning its descendant objects.
-
-.. code-block:: python
-
-    class EventPageIndex(Page):
-        # ...
-        def events(self):
-            # Get list of live event pages that are descendants of this page
-            events = EventPage.objects.live().descendant_of(self)
-
-            # Filter events list to get ones that are either
-            # running now or start in the future
-            events = events.filter(date_from__gte=date.today())
-
-            # Order by date
-            events = events.order_by('date_from')
-
-            return events
-
-This example makes sure to limit the returned objects to pieces of content which make sense, specifically ones which have been published through Wagtail's admin interface (``live()``) and are children of this node (``descendant_of(self)``). By setting a ``subpage_types`` class property in your model, you can specify which models are allowed to be set as children, but Wagtail will allow any ``Page``-derived model by default. Regardless, it's smart for a parent model to provide an index filtered to make sense.
-
-
-Leaves
-``````
-Leaves are the pieces of content itself, a page which is consumable, and might just consist of a bunch of properties. A blog page leaf might have some body text and an image. A person page leaf might have a photo, a name, and an address.
-
-It might be helpful for a leaf to provide a way to back up along the tree to a parent, such as in the case of breadcrumbs navigation. The tree might also be deep enough that a leaf's parent won't be included in general site navigation.
-
-The model for the leaf could provide a function that traverses the tree in the opposite direction and returns an appropriate ancestor:
-
-.. code-block:: python
-
-    class EventPage(Page):
-        # ...
-        def event_index(self):
-            # Find closest ancestor which is an event index
-            return self.get_ancestors().type(EventIndexPage).last()
-
-If defined, ``subpage_types`` will also limit the parent models allowed to contain a leaf. If not, Wagtail will allow any combination of parents and leafs to be associated in the Wagtail tree. Like with index pages, it's a good idea to make sure that the index is actually of the expected model to contain the leaf.
-
-
-Other Relationships
-```````````````````
-Your ``Page``-derived models might have other interrelationships which extend the basic Wagtail tree or depart from it entirely. You could provide functions to navigate between siblings, such as a "Next Post" link on a blog page (``post->post->post``). It might make sense for subtrees to interrelate, such as in a discussion forum (``forum->post->replies``) Skipping across the hierarchy might make sense, too, as all objects of a certain model class might interrelate regardless of their ancestors (``events = EventPage.objects.all``). It's largely up to the models to define their interrelations, the possibilities are really endless.
-
-
-.. _anatomy_of_a_wagtail_request:
-
-Anatomy of a Wagtail Request
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For going beyond the basics of model definition and interrelation, it might help to know how Wagtail handles requests and constructs responses. In short, it goes something like:
-
-    #.  Django gets a request and routes through Wagtail's URL dispatcher definitions
-    #.  Wagtail checks the hostname of the request to determine which ``Site`` record will handle this request.
-    #.  Starting from the root page of that site, Wagtail traverses the page tree, calling the ``route()`` method and letting each page model decide whether it will handle the request itself or pass it on to a child page.
-    #.  The page responsible for handling the request returns a ``RouteResult`` object from ``route()``, which identifies the page along with any additional args/kwargs to be passed to ``serve()``.
-    #.  Wagtail calls ``serve()``, which constructs a context using ``get_context()``
-    #.  ``serve()`` finds a template to pass it to using ``get_template()``
-    #.  A response object is returned by ``serve()`` and Django responds to the requester.
-
-You can apply custom behavior to this process by overriding ``Page`` class methods such as ``route()`` and ``serve()`` in your own models. For examples, see :ref:`model_recipes`.
-
-
-Page Properties and Methods Reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In addition to the model fields provided, ``Page`` has many properties and methods that you may wish to reference, use, or override in creating your own models. Those listed here are relatively straightforward to use, but consult the Wagtail source code for a full view of what's possible.
-
-.. automodule:: wagtail.wagtailcore.models
-.. autoclass:: Page
-
-    .. autoattribute:: specific
-
-    .. autoattribute:: specific_class
-
-    .. autoattribute:: url
-
-    .. autoattribute:: full_url
-
-    .. automethod:: relative_url
-
-    .. automethod:: is_navigable
-
-    .. automethod:: route
-
-    .. automethod:: serve
-
-    .. automethod:: get_context
-
-    .. automethod:: get_template
-
-    .. autoattribute:: preview_modes
-
-    .. automethod:: serve_preview
-
-    .. automethod:: get_ancestors
-
-    .. automethod:: get_descendants
-
-    .. automethod:: get_siblings
-
-    .. automethod:: search
-
-
-Page Queryset Reference
-~~~~~~~~~~~~~~~~~~~~~~~
-
-All models that inherit from ``Page`` are given some extra Queryset methods accessible from their ``.objects`` attribute.
-
-Examples:
-
- - Selecting only live pages
-
-    .. code-block:: python
-
-        live_pages = Page.objects.live()
-
- - Selecting published EventPages that are descendants of events_index
-
-    .. code-block:: python
-
-        events = EventPage.objects.live().descendant_of(events_index)
-
- - Getting a list of menu items
-
-    .. code-block:: python
-
-        # This gets a queryset of live children of the homepage with ``show_in_menus`` set
-        menu_items = homepage.get_children().live().in_menu()
-
-
-.. automodule:: wagtail.wagtailcore.query
-.. autoclass:: PageQuerySet
-
-    .. automethod:: live
-
-        Example:
-
-        .. code-block:: python
-
-            published_pages = Page.objects.live()
-
-    .. automethod:: not_live
-
-        Example:
-
-        .. code-block:: python
-
-            unpublished_pages = Page.objects.not_live()
-
-    .. automethod:: in_menu
-
-        Example:
-
-        .. code-block:: python
-
-            # Build a menu from live pages that are children of the homepage
-            menu_items = homepage.get_children().live().in_menu()
-
-
-        .. note::
-
-            To put your page in menus, set the show_in_menus flag to true:
-
-            .. code-block:: python
-
-                # Add 'my_page' to the menu
-                my_page.show_in_menus = True
-
-    .. automethod:: page
-
-        Example:
-
-        .. code-block:: python
-
-            # Append an extra page to a queryset
-            new_queryset = old_queryset | Page.objects.page(page_to_add)
-
-    .. automethod:: not_page
-
-        Example:
-
-        .. code-block:: python
-
-            # Remove a page from a queryset
-            new_queryset = old_queryset & Page.objects.not_page(page_to_remove)
-
-    .. automethod:: descendant_of
-
-        Example:
-
-        .. code-block:: python
-
-            # Get EventPages that are under the special_events Page
-            special_events = EventPage.objects.descendant_of(special_events_index)
-
-            # Alternative way
-            special_events = special_events_index.get_descendants()
-
-    .. automethod:: not_descendant_of
-
-        Example:
-
-        .. code-block:: python
-
-            # Get EventPages that are not under the archived_events Page
-            non_archived_events = EventPage.objects.not_descendant_of(archived_events_index)
-
-    .. automethod:: child_of
-
-        Example:
-
-        .. code-block:: python
-
-            # Get a list of sections
-            sections = Page.objects.child_of(homepage)
-
-            # Alternative way
-            sections = homepage.get_children()
-
-    .. automethod:: ancestor_of
-
-        Example:
-
-        .. code-block:: python
-
-            # Get the current section
-            current_section = Page.objects.ancestor_of(current_page).child_of(homepage).first()
-
-            # Alternative way
-            current_section = current_page.get_ancestors().child_of(homepage).first()
-
-    .. automethod:: not_ancestor_of
-
-        Example:
-
-        .. code-block:: python
-
-            # Get the other sections
-            other_sections = Page.objects.not_ancestor_of(current_page).child_of(homepage)
-
-    .. automethod:: sibling_of
-
-        Example:
-
-        .. code-block:: python
-
-            # Get list of siblings
-            siblings = Page.objects.sibling_of(current_page)
-
-            # Alternative way
-            siblings = current_page.get_siblings()
-
-    .. automethod:: public
-
-        See: :ref:`private_pages`
-
-        .. note::
-
-            This doesn't filter out unpublished pages. If you want to only have published public pages, use ``.live().public()``
-
-        Example:
-
-        .. code-block:: python
-
-            # Find all the pages that are viewable by the public
-            all_pages = Page.objects.live().public()
-
-    .. automethod:: search
-
-        See: :ref:`wagtailsearch_for_python_developers`
-
-        Example:
-
-        .. code-block:: python
-
-            # Search future events
-            results = EventPage.objects.live().filter(date__gt=timezone.now()).search("Hello")
-
-
-.. _wagtail_site_admin:
-
-Site
-~~~~
-
-Django's built-in admin interface provides the way to map a "site" (hostname or domain) to any node in the wagtail tree, using that node as the site's root.
-
-Access this by going to ``/django-admin/`` and then "Home › Wagtailcore › Sites." To try out a development site, add a single site with the hostname ``localhost`` at port ``8000`` and map it to one of the pieces of content you have created.
-
-Wagtail's developers plan to move the site settings into the Wagtail admin interface.
-
-
-.. _redirects:
-
-Redirects
-~~~~~~~~~
-
-Wagtail provides a simple interface for creating arbitrary redirects to and from any URL.
-
-.. image:: ../images/screen_wagtail_redirects.png

docs/building_your_site/index.rst

@@ -1,11 +0,0 @@
-Building your site
-==================
-
-.. note::
-	This documentation is currently incomplete.
-
-.. toctree::
-   :maxdepth: 3
-
-   djangodevelopers
-   frontenddevelopers

docs/conf.py

@@ -70,9 +70,9 @@ copyright = u'2014, Torchbox'
 # built documents.
 #
 # The short X.Y version.
-version = '0.4'
+version = '0.5'
 # The full version, including alpha/beta/rc tags.
-release = '0.4'
+release = '0.5'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/contrib_components/frontend_cache_purging.rst

@@ -42,8 +42,8 @@ Finally, make sure you have configured your frontend cache to accept PURGE reque
  - `Squid <http://wiki.squid-cache.org/SquidFaq/OperatingSquid#How_can_I_purge_an_object_from_my_cache.3F>`_
 
 
-Advanced useage
-~~~~~~~~~~~~~~~
+Advanced usage
+~~~~~~~~~~~~~~
 
 Purging more than one URL per page
 ----------------------------------

docs/contrib_components/index.rst

@@ -0,0 +1,11 @@
+Contrib components
+==================
+
+
+.. toctree::
+    :maxdepth: 2
+
+    static_site_generation
+    sitemap_generation
+    frontend_cache_purging
+

docs/core_components/images/feature_detection.rst

@@ -0,0 +1,88 @@
+.. _image_feature_detection:
+
+=================
+Feature Detection
+=================
+
+Wagtail has the ability to automatically detect faces and features inside your images and crop the images to those features.
+
+Feature detection uses OpenCV to detect faces/features in an image when the image is uploaded. The detected features stored internally as a focal point in the ``focal_point_{x, y, width, height}`` fields on the ``Image`` model. These fields are used by the ``fill`` image filter when an image is rendered in a template to crop the image.
+
+
+Setup
+=====
+
+Feature detection requires OpenCV which can be a bit tricky to install as it's not currently pip-installable.
+
+
+Installing OpenCV on Debian/Ubuntu
+----------------------------------
+
+Debian and ubuntu provide an apt-get package called ``python-opencv``:
+
+ .. code-block:: bash
+
+    sudo apt-get install python-opencv python-numpy
+
+This will install PyOpenCV into your site packages. If you are using a virtual environment, you need to make sure site packages are enabled or Wagtail will not be able to import PyOpenCV.
+
+
+Enabling site packages in the virtual environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you are not using a virtual envionment, you can skip this step.
+
+Enabling site packages is different depending on whether you are using pyvenv (Python 3.3+ only) or virtualenv to manage your virtual environment.
+
+
+pyvenv
+``````
+
+Go into your pyvenv directory and open the ``pyvenv.cfg`` file then set ``include-system-site-packages`` to ``true``.
+
+
+virtualenv
+``````````
+
+Go into your virtualenv directory and delete a file called ``lib/python-x.x/no-global-site-packages.txt``.
+
+
+Testing the OpenCV installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can test that OpenCV can be seen by Wagtail by opening up a python shell (with your virtual environment active) and typing:
+
+ .. code-block:: python
+
+    import cv
+
+If you don't see an ``ImportError``, it worked. (If you see the error ``libdc1394 error: Failed to initialize libdc1394``, this is harmless and can be ignored.)
+
+
+Switching on feature detection in Wagtail
+-----------------------------------------
+
+Once OpenCV is installed, you need to set the ``WAGTAILIMAGES_FEATURE_DETECTION_ENABLED`` setting to ``True``:
+
+ .. code-block:: python
+
+    # settings.py
+
+    WAGTAILIMAGES_FEATURE_DETECTION_ENABLED = True
+
+
+Manually running feature detection
+----------------------------------
+
+Feature detection runs when new images are uploaded in to Wagtail. If you already have images in your Wagtail site and would like to run feature detection on them, you will have to run it manually.
+
+You can manually run feature detection on all images by running the following code in the python shell:
+
+ .. code-block:: python
+
+    from wagtail.wagtailimages.models import Image
+
+    for image in Image.objects.all():
+        if image.focal_point is None:
+            image.focal_point = image.get_suggested_focal_point()
+            image.save()

docs/core_components/images/index.rst

@@ -0,0 +1,9 @@
+Images
+======
+
+.. toctree::
+    :maxdepth: 2
+
+    using_images_outside_wagtail
+    feature_detection
+

docs/core_components/images/using_images_outside_wagtail.rst

@@ -0,0 +1,82 @@
+.. _using_images_outside_wagtail:
+
+============================
+Using images outside Wagtail
+============================
+
+Wagtail provides a way for you to generate external URLs for images in your image library which you can use to display your images on external sites.
+
+
+Setup
+=====
+
+Add an entry in your URLs configuration for ``wagtail.wagtailimages.urls``:
+
+ .. code-block:: python
+
+    from wagtail.wagtailimages import urls as wagtailimages_urls
+
+
+    urlpatterns = patterns('',
+        ...
+
+        url(r'^images/', include(wagtailimages_urls)),
+
+        ...
+    )
+
+
+Generating URLs for images
+==========================
+
+Once the above setup is done, a button should appear under the image preview on the image edit page. Clicking this button will take you to an interface where you can specify the size you want the image to be, and it will generate a URL and a preview of what the image is going to look like.
+
+The filter box lets you choose how you would like the image to be resized:
+
+
+.. glossary::
+    ``Original`` 
+
+        Leaves the image at its original size - no resizing is performed.
+
+    ``Resize to max`` 
+
+        Fit **within** the given dimensions. 
+
+        The longest edge will be reduced to the equivalent dimension size defined. e.g A portrait image of width 1000, height 2000, treated with the ``max`` dimensions ``1000x500`` (landscape) would result in the image shrunk so the *height* was 500 pixels and the width 250.
+
+    ``Resize to min`` 
+
+        **Cover** the given dimensions.
+
+        This may result in an image slightly **larger** than the dimensions you specify. e.g A square image of width 2000, height 2000, treated with the ``min`` dimensions ``500x200`` (landscape) would have it's height and width changed to 500, i.e matching the width required, but greater than the height.
+
+    ``Resize to width`` 
+
+        Reduces the width of the image to the dimension specified.
+
+    ``Resize to height`` 
+
+        Resize the height of the image to the dimension specified.. 
+
+    ``Resize to fill`` 
+
+        Resize and **crop** to fill the **exact** dimensions. 
+
+        This can be particularly useful for websites requiring square thumbnails of arbitrary images. For example, a landscape image of width 2000, height 1000, treated with ``fill`` dimensions ``200x200`` would have its height reduced to 200, then its width (ordinarily 400) cropped to 200. 
+
+
+Using the URLs on your website or blog
+======================================
+
+Once you have generated a URL, you can put it straight into the ``src`` attribute of an ``<img>`` tag:
+
+ .. code-block:: html
+
+    <img src="(image url here)">
+
+
+Performance
+===========
+
+Currently, Wagtail will regenerate the image every time it is requested. For high volume sites, it is recommended to use a frontend cache to reduce load on the backend servers.

docs/core_components/index.rst

@@ -0,0 +1,13 @@
+Core components
+===============
+
+.. toctree::
+    :maxdepth: 2
+
+    sites
+    pages/index
+    images/index
+    snippets
+    search/index
+    form_builder
+

docs/core_components/pages/advanced_topics/queryset_methods.rst

@@ -0,0 +1,180 @@
+=====================
+Page Queryset Methods
+=====================
+
+All models that inherit from ``Page`` are given some extra Queryset methods accessible from their ``.objects`` attribute.
+
+
+Examples
+========
+
+ - Selecting only live pages
+
+    .. code-block:: python
+
+        live_pages = Page.objects.live()
+
+ - Selecting published EventPages that are descendants of events_index
+
+    .. code-block:: python
+
+        events = EventPage.objects.live().descendant_of(events_index)
+
+ - Getting a list of menu items
+
+    .. code-block:: python
+
+        # This gets a queryset of live children of the homepage with ``show_in_menus`` set
+        menu_items = homepage.get_children().live().in_menu()
+
+
+Reference
+=========
+
+.. automodule:: wagtail.wagtailcore.query
+.. autoclass:: PageQuerySet
+
+    .. automethod:: live
+
+        Example:
+
+        .. code-block:: python
+
+            published_pages = Page.objects.live()
+
+    .. automethod:: not_live
+
+        Example:
+
+        .. code-block:: python
+
+            unpublished_pages = Page.objects.not_live()
+
+    .. automethod:: in_menu
+
+        Example:
+
+        .. code-block:: python
+
+            # Build a menu from live pages that are children of the homepage
+            menu_items = homepage.get_children().live().in_menu()
+
+
+        .. note::
+
+            To put your page in menus, set the show_in_menus flag to true:
+
+            .. code-block:: python
+
+                # Add 'my_page' to the menu
+                my_page.show_in_menus = True
+
+    .. automethod:: page
+
+        Example:
+
+        .. code-block:: python
+
+            # Append an extra page to a queryset
+            new_queryset = old_queryset | Page.objects.page(page_to_add)
+
+    .. automethod:: not_page
+
+        Example:
+
+        .. code-block:: python
+
+            # Remove a page from a queryset
+            new_queryset = old_queryset & Page.objects.not_page(page_to_remove)
+
+    .. automethod:: descendant_of
+
+        Example:
+
+        .. code-block:: python
+
+            # Get EventPages that are under the special_events Page
+            special_events = EventPage.objects.descendant_of(special_events_index)
+
+            # Alternative way
+            special_events = special_events_index.get_descendants()
+
+    .. automethod:: not_descendant_of
+
+        Example:
+
+        .. code-block:: python
+
+            # Get EventPages that are not under the archived_events Page
+            non_archived_events = EventPage.objects.not_descendant_of(archived_events_index)
+
+    .. automethod:: child_of
+
+        Example:
+
+        .. code-block:: python
+
+            # Get a list of sections
+            sections = Page.objects.child_of(homepage)
+
+            # Alternative way
+            sections = homepage.get_children()
+
+    .. automethod:: ancestor_of
+
+        Example:
+
+        .. code-block:: python
+
+            # Get the current section
+            current_section = Page.objects.ancestor_of(current_page).child_of(homepage).first()
+
+            # Alternative way
+            current_section = current_page.get_ancestors().child_of(homepage).first()
+
+    .. automethod:: not_ancestor_of
+
+        Example:
+
+        .. code-block:: python
+
+            # Get the other sections
+            other_sections = Page.objects.not_ancestor_of(current_page).child_of(homepage)
+
+    .. automethod:: sibling_of
+
+        Example:
+
+        .. code-block:: python
+
+            # Get list of siblings
+            siblings = Page.objects.sibling_of(current_page)
+
+            # Alternative way
+            siblings = current_page.get_siblings()
+
+    .. automethod:: public
+
+        See: :ref:`private_pages`
+
+        .. note::
+
+            This doesn't filter out unpublished pages. If you want to only have published public pages, use ``.live().public()``
+
+        Example:
+
+        .. code-block:: python
+
+            # Find all the pages that are viewable by the public
+            all_pages = Page.objects.live().public()
+
+    .. automethod:: search
+
+        See: :ref:`wagtailsearch_for_python_developers`
+
+        Example:
+
+        .. code-block:: python
+
+            # Search future events
+            results = EventPage.objects.live().filter(date__gt=timezone.now()).search("Hello")

docs/core_components/pages/advanced_topics/routable_page_mixin.rst

@@ -0,0 +1,119 @@
+.. _routable_page_mixin:
+
+====================================
+Embedding URL configuration in Pages
+====================================
+
+.. versionadded:: 0.5
+
+The ``RoutablePageMixin`` mixin provides a convenient way for a page to respond on multiple sub-URLs with different views. For example, a blog section on a site might provide several different types of index page at URLs like ``/blog/2013/06/``, ``/blog/authors/bob/``, ``/blog/tagged/python/``, all served by the same ``BlogIndex`` page.
+
+A ``Page`` using ``RoutablePageMixin`` exists within the page tree like any other page, but URL paths underneath it are checked against a list of patterns, using Django's urlconf scheme. If none of the patterns match, control is passed to subpages as usual (or failing that, a 404 error is thrown).
+
+
+The basics
+==========
+
+To use ``RoutablePageMixin``, you need to make your class inherit from both :class:`wagtail.contrib.wagtailroutablepage.models.RoutablePageMixin` and :class:`wagtail.wagtailcore.models.Page`, and configure the ``subpage_urls`` attribute with your URL configuration.
+
+Here's an example of an ``EventPage`` with three views:
+
+.. code-block:: python
+
+    from django.conf.urls import url
+
+    from wagtail.contrib.wagtailroutablepage.models import RoutablePageMixin
+    from wagtail.wagtailcore.models import Page
+
+
+    class EventPage(RoutablePageMixin, Page):
+        subpage_urls = (
+            url(r'^$', 'current_events', name='current_events'),
+            url(r'^past/$', 'past_events', name='past_events'),
+            url(r'^year/(\d+)/$', 'events_for_year', name='events_for_year'),
+        )
+
+        def current_events(self, request):
+            """
+            View function for the current events page
+            """
+            ...
+
+        def past_events(self, request):
+            """
+            View function for the past events page
+            """
+            ...
+
+        def events_for_year(self, request):
+            """
+            View function for the events for year page
+            """
+            ...
+
+
+The ``RoutablePageMixin`` class
+===============================
+
+.. automodule:: wagtail.contrib.wagtailroutablepage.models
+.. autoclass:: RoutablePageMixin
+
+    .. autoattribute:: subpage_urls
+
+        Example:
+
+        .. code-block:: python
+
+            from django.conf.urls import url
+
+            from wagtail.wagtailcore.models import Page
+
+            class MyPage(RoutablePageMixin, Page):
+                subpage_urls = (
+                    url(r'^$', 'serve', name='main'),
+                    url(r'^archive/$', 'archive', name='archive'),
+                )
+
+                def serve(self, request):
+                    ...
+
+                def archive(self, request):
+                    ...
+
+    .. automethod:: resolve_subpage
+
+        Example:
+
+        .. code-block:: python
+
+            view, args, kwargs = page.resolve_subpage('/past/')
+            response = view(request, *args, **kwargs)
+
+    .. automethod:: reverse_subpage
+
+        Example:
+
+        .. code-block:: python
+
+            url = page.url + page.reverse_subpage('events_for_year', args=('2014', ))
+
+
+ .. _routablepageurl_template_tag:
+
+The ``routablepageurl`` template tag
+====================================
+
+.. versionadded:: 0.6
+
+.. currentmodule:: wagtail.contrib.wagtailroutablepage.templatetags.wagtailroutablepage_tags
+.. autofunction:: routablepageurl
+
+    Example:
+
+    .. code-block:: html+django
+
+        {% load wagtailroutablepage_tags %}
+
+        {% routablepageurl self "feed" %}
+        {% routablepageurl self "archive" 2014 08 14 %}
+        {% routablepageurl self "food" foo="bar" baz="quux" %}

docs/core_components/pages/creating_pages.rst

@@ -0,0 +1,149 @@
+====================
+Creating page models
+====================
+
+Wagtail provides a ``Page`` class to represent types of page (a.k.a Content types). Developers should subclass ``Page`` for their own page models. 
+
+``Page`` uses Django's model interface, so you can include any field type and field options that Django allows. Wagtail provides some field types of its own which simplify data entry in the Wagtail admin interface. Wagtail also wraps Django's field types and widgets with its own concept of "Edit Handlers" and "Panels". These further improve the data entry experience.
+
+
+An example Wagtail Page Model
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This example represents a typical blog post:
+
+.. code-block:: python
+
+    from django.db import models
+
+    from wagtail.wagtailcore.models import Page
+    from wagtail.wagtailcore.fields import RichTextField
+    from wagtail.wagtailadmin.edit_handlers import FieldPanel
+    from wagtail.wagtailimages.edit_handlers import ImageChooserPanel
+    from wagtail.wagtailimages.models import Image
+
+    class BlogPage(Page):
+        body = RichTextField()
+        date = models.DateField("Post date")
+        feed_image = models.ForeignKey(
+            'wagtailimages.Image',
+            null=True,
+            blank=True,
+            on_delete=models.SET_NULL,
+            related_name='+'
+        )
+
+
+
+    BlogPage.content_panels = [
+        FieldPanel('title', classname="full title"),
+        FieldPanel('date'),
+        FieldPanel('body', classname="full"),
+    ]
+
+    BlogPage.promote_panels = [
+        FieldPanel('slug'),
+        FieldPanel('seo_title'),
+        FieldPanel('show_in_menus'),
+        FieldPanel('search_description'),
+        ImageChooserPanel('feed_image'),
+    ]
+
+.. tip::
+    To keep track of ``Page`` models and avoid class name clashes, it can be helpful to suffix model class names with "Page" e.g BlogPage, ListingIndexPage. 
+
+In the example above the ``BlogPage`` class defines three properties: ``body``, ``date``, and ``feed_image``. These are a mix of basic Django models (``DateField``), Wagtail fields (``RichTextField``), and a pointer to a Wagtail model (``Image``).
+
+Below that the ``content_panels`` and ``promote_panels`` lists define the capabilities and layout of the page editing interface in the Wagtail admin. The lists are filled with "panels" and "choosers", which will provide a fine-grain interface for inputting the model's content. The ``ImageChooserPanel``, for instance, lets one browse the image library, upload new images and input image metadata. The ``RichTextField`` is the basic field for creating web-ready website rich text, including text formatting and embedded media like images and video. The Wagtail admin offers other choices for fields, Panels, and Choosers, with the option of creating your own to precisely fit your content without workarounds or other compromises.
+
+Your models may be even more complex, with methods overriding the built-in functionality of the ``Page`` to achieve webdev magic. Or, you can keep your models simple and let Wagtail's built-in functionality do the work.
+
+
+``Page`` Class Reference
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Default fields
+--------------
+
+Wagtail provides some fields for the ``Page`` class by default, which will be common to all your pages. You don't need to add these fields to your own page models however you do need to allocate them to ``content_panels``, ``promote_panels`` or ``settings_panels``. See above example and for further information on the panels see :ref:`editing-api`.
+
+    ``title`` (string, required)
+        Human-readable title of the page - what you'd probably use as your ``<h1>`` tag.
+
+    ``slug`` (string, required)
+        Machine-readable URL component for this page. The name of the page as it will appear in URLs e.g ``http://domain.com/blog/[my-slug]/``
+
+    ``seo_title`` (string)
+        Alternate SEO-crafted title, mainly for use in the page ``<title>`` tag.
+
+    ``search_description`` (string)
+        SEO-crafted description of the content, used for internal search indexing, suitable for your page's ``<meta name="description">`` tag.
+
+    ``show_in_menus`` (boolean)
+        Toggles whether the page should be considered for inclusion in any site-wide menus you create.
+
+    ``go_live_at`` (datetime)
+        A datetime on which the page should be automatically made published (made publicly accessible)
+
+    ``expire_at`` (datetime)
+        A datetime on which the page should be unpublished, rendering it inaccessible to the public.
+
+
+Page Attributes, Properties and Methods Reference
+-------------------------------------------------
+
+In addition to the model fields provided, ``Page`` has many properties and methods that you may wish to reference, use, or override in creating your own models. Those listed here are relatively straightforward to use, but consult the Wagtail source code for a full view of what's possible.
+
+.. automodule:: wagtail.wagtailcore.models
+.. autoclass:: Page
+
+    .. autoattribute:: specific
+
+    .. autoattribute:: specific_class
+
+    .. autoattribute:: url
+
+    .. autoattribute:: full_url
+
+    .. automethod:: relative_url
+
+    .. automethod:: is_navigable
+
+    .. automethod:: route
+
+    .. automethod:: serve
+
+    .. automethod:: get_context
+
+    .. automethod:: get_template
+
+    .. autoattribute:: preview_modes
+
+    .. automethod:: serve_preview
+
+    .. automethod:: get_ancestors
+
+    .. automethod:: get_descendants
+
+    .. automethod:: get_siblings
+
+    .. automethod:: search
+
+    .. attribute:: search_fields
+        
+        A list of fields to be indexed by the search engine. See Search docs :ref:`wagtailsearch_for_python_developers`
+
+    .. attribute:: subpage_types
+
+        A whitelist of page models which can be created as children of this page type e.g a ``BlogIndex`` page might allow ``BlogPage``, but not ``JobPage`` e.g
+
+        .. code-block:: python
+
+            class BlogIndex(Page):
+                subpage_types = ['mysite.BlogPage', 'mysite.BlogArchivePage']
+
+    .. attribute:: password_required_template
+
+        Defines which template file should be used to render the login form for Protected pages using this model. This overrides the default, defined using ``PASSWORD_REQUIRED_TEMPLATE`` in your settings. See :ref:`private_pages`
+
+

docs/core_components/pages/editing_api.rst

@@ -1,3 +1,4 @@
+.. _editing-api:
 
 Defining models with the Editing API
 ====================================

docs/core_components/pages/index.rst

@@ -0,0 +1,24 @@
+Pages
+=====
+
+.. note::
+    This documentation is currently being written.
+
+Wagtail requires a little careful setup to define the types of content that you want to present through your website. The basic unit of content in Wagtail is the ``Page``, and all of your page-level content will inherit basic webpage-related properties from it. But for the most part, you will be defining content yourself, through the construction of Django models using Wagtail's ``Page`` as a base.
+
+Wagtail organizes content created from your models in a tree, which can have any structure and combination of model objects in it. Wagtail doesn't prescribe ways to organize and interrelate your content, but here we've sketched out some strategies for organizing your models.
+
+The presentation of your content, the actual webpages, includes the normal use of the Django template system. We'll cover additional functionality that Wagtail provides at the template level later on.
+
+
+.. toctree::
+    :maxdepth: 2
+
+    theory
+    creating_pages
+    writing_templates
+    model_recipes
+    editing_api
+    advanced_topics/queryset_methods
+    advanced_topics/private_pages
+    advanced_topics/routable_page_mixin

docs/core_components/pages/model_recipes.rst

@@ -1,8 +1,8 @@
 
 .. _model_recipes:
 
-Model Recipes
-=============
+Recipes
+=======
 
 Overriding the serve() Method
 -----------------------------

docs/core_components/pages/theory.rst

@@ -0,0 +1,97 @@
+.. _pages-theory:
+
+======
+Theory
+======
+
+
+Introduction to Trees
+~~~~~~~~~~~~~~~~~~~~~
+
+If you're unfamiliar with trees as an abstract data type, you might want to `review the concepts involved. <http://en.wikipedia.org/wiki/Tree_(data_structure)>`_
+
+As a web developer, though, you probably already have a good understanding of trees as filesystem directories or paths. Wagtail pages can create the same structure, as each page in the tree has its own URL path, like so::
+
+    /
+        people/
+            nien-nunb/
+            laura-roslin/
+        events/
+            captain-picard-day/
+            winter-wrap-up/
+
+The Wagtail admin interface uses the tree to organize content for editing, letting you navigate up and down levels in the tree through its Explorer menu. This method of organization is a good place to start in thinking about your own Wagtail models.
+
+
+Nodes and Leaves
+----------------
+
+It might be handy to think of the ``Page``-derived models you want to create as being one of two node types: parents and leaves. Wagtail isn't prescriptive in this approach, but it's a good place to start if you're not experienced in structuring your own content types.
+
+
+Nodes
+`````
+Parent nodes on the Wagtail tree probably want to organize and display a browse-able index of their descendants. A blog, for instance, needs a way to show a list of individual posts.
+
+A Parent node could provide its own function returning its descendant objects.
+
+.. code-block:: python
+
+    class EventPageIndex(Page):
+        # ...
+        def events(self):
+            # Get list of live event pages that are descendants of this page
+            events = EventPage.objects.live().descendant_of(self)
+
+            # Filter events list to get ones that are either
+            # running now or start in the future
+            events = events.filter(date_from__gte=date.today())
+
+            # Order by date
+            events = events.order_by('date_from')
+
+            return events
+
+This example makes sure to limit the returned objects to pieces of content which make sense, specifically ones which have been published through Wagtail's admin interface (``live()``) and are children of this node (``descendant_of(self)``). By setting a ``subpage_types`` class property in your model, you can specify which models are allowed to be set as children, but Wagtail will allow any ``Page``-derived model by default. Regardless, it's smart for a parent model to provide an index filtered to make sense.
+
+
+Leaves
+``````
+Leaves are the pieces of content itself, a page which is consumable, and might just consist of a bunch of properties. A blog page leaf might have some body text and an image. A person page leaf might have a photo, a name, and an address.
+
+It might be helpful for a leaf to provide a way to back up along the tree to a parent, such as in the case of breadcrumbs navigation. The tree might also be deep enough that a leaf's parent won't be included in general site navigation.
+
+The model for the leaf could provide a function that traverses the tree in the opposite direction and returns an appropriate ancestor:
+
+.. code-block:: python
+
+    class EventPage(Page):
+        # ...
+        def event_index(self):
+            # Find closest ancestor which is an event index
+            return self.get_ancestors().type(EventIndexPage).last()
+
+If defined, ``subpage_types`` will also limit the parent models allowed to contain a leaf. If not, Wagtail will allow any combination of parents and leafs to be associated in the Wagtail tree. Like with index pages, it's a good idea to make sure that the index is actually of the expected model to contain the leaf.
+
+
+Other Relationships
+```````````````````
+Your ``Page``-derived models might have other interrelationships which extend the basic Wagtail tree or depart from it entirely. You could provide functions to navigate between siblings, such as a "Next Post" link on a blog page (``post->post->post``). It might make sense for subtrees to interrelate, such as in a discussion forum (``forum->post->replies``) Skipping across the hierarchy might make sense, too, as all objects of a certain model class might interrelate regardless of their ancestors (``events = EventPage.objects.all``). It's largely up to the models to define their interrelations, the possibilities are really endless.
+
+
+.. _anatomy_of_a_wagtail_request:
+
+Anatomy of a Wagtail Request
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For going beyond the basics of model definition and interrelation, it might help to know how Wagtail handles requests and constructs responses. In short, it goes something like:
+
+    #.  Django gets a request and routes through Wagtail's URL dispatcher definitions
+    #.  Wagtail checks the hostname of the request to determine which ``Site`` record will handle this request.
+    #.  Starting from the root page of that site, Wagtail traverses the page tree, calling the ``route()`` method and letting each page model decide whether it will handle the request itself or pass it on to a child page.
+    #.  The page responsible for handling the request returns a ``RouteResult`` object from ``route()``, which identifies the page along with any additional args/kwargs to be passed to ``serve()``.
+    #.  Wagtail calls ``serve()``, which constructs a context using ``get_context()``
+    #.  ``serve()`` finds a template to pass it to using ``get_template()``
+    #.  A response object is returned by ``serve()`` and Django responds to the requester.
+
+You can apply custom behavior to this process by overriding ``Page`` class methods such as ``route()`` and ``serve()`` in your own models. For examples, see :ref:`model_recipes`.

docs/core_components/pages/writing_templates.rst

@@ -181,6 +181,7 @@ The available resizing methods are:
 
         Leaves the image at its original size - no resizing is performed.
 
+
 .. Note::
     Wagtail does not allow deforming or stretching images. Image dimension ratios will always be kept. Wagtail also *does not support upscaling*. Small images forced to appear at larger sizes will "max out" at their their native dimensions.
 

docs/core_components/search/for_python_developers.rst

@@ -36,6 +36,11 @@ Indexing extra fields
     The ``indexed_fields`` configuration format was replaced with ``search_fields``
 
 
+.. note::
+
+    Searching on extra fields with the database backend is not currently supported.
+
+
 Fields need to be explicitly added to the search configuration in order for you to be able to search/filter on them.
 
 You can add new fields to the search index by overriding the ``search_fields`` property and appending a list of extra ``SearchField``/``FilterField`` objects to it.

docs/core_components/sites.rst

@@ -0,0 +1,10 @@
+.. _wagtail_site_admin:
+
+Sites
+=====
+
+Django's built-in admin interface provides the way to map a "site" (hostname or domain) to any node in the wagtail tree, using that node as the site's root. See :ref:`pages-theory`.
+
+Access this by going to ``/django-admin/`` and then "Home › Wagtailcore › Sites." To try out a development site, add a single site with the hostname ``localhost`` at port ``8000`` and map it to one of the pieces of content you have created.
+
+Wagtail's developers plan to move the site settings into the Wagtail admin interface.

docs/core_components/snippets.rst

@@ -92,26 +92,49 @@ Then in your own page templates, you can include your snippet template tag with:
 
   {% endblock %}
 
+
 Binding Pages to Snippets
 -------------------------
 
-An alternate strategy for including snippets might involve explicitly binding a specific page object to a specific snippet object. Lets add another snippet class to see how that might work:
+In the above example, the list of adverts is a fixed list, displayed as part of the template independently of the page content. This might be what you want for a common panel in a sidebar, say - but in other scenarios you may wish to refer to a snippet within page content. This can be done by defining a foreign key to the snippet model within your page model, and adding a ``SnippetChooserPanel`` to the page's ``content_panels`` definitions. For example, if you wanted to be able to specify an advert to appear on ``BookPage``:
+
+.. code-block:: python
+
+  from wagtail.wagtailsnippets.edit_handlers import SnippetChooserPanel
+  # ...
+  class BookPage(Page):
+    advert = models.ForeignKey(
+      'demo.Advert',
+      null=True,
+      blank=True,
+      on_delete=models.SET_NULL,
+      related_name='+'
+    )
+
+  BookPage.content_panels = [
+    SnippetChooserPanel('advert', Advert),
+    # ...
+  ]
+
+
+The snippet could then be accessed within your template as ``self.advert``.
+
+To attach multiple adverts to a page, the ``SnippetChooserPanel`` can be placed on an inline child object of ``BookPage``, rather than on ``BookPage`` itself. Here this child model is named ``BookPageAdvertPlacement`` (so called because there is one such object for each time that an advert is placed on a BookPage):
+
 
 .. code-block:: python
 
   from django.db import models
 
   from wagtail.wagtailcore.models import Page
-  from wagtail.wagtailadmin.edit_handlers import PageChooserPanel
-  from wagtail.wagtailsnippets.models import register_snippet
   from wagtail.wagtailsnippets.edit_handlers import SnippetChooserPanel
 
   from modelcluster.fields import ParentalKey
   
   ...
 
-  class AdvertPlacement(models.Model):
-    page = ParentalKey('wagtailcore.Page', related_name='advert_placements')
+  class BookPageAdvertPlacement(Orderable, models.Model):
+    page = ParentalKey('demo.BookPage', related_name='advert_placements')
     advert = models.ForeignKey('demo.Advert', related_name='+')
 
     class Meta:
@@ -119,25 +142,27 @@ An alternate strategy for including snippets might involve explicitly binding a
       verbose_name_plural = "Advert Placements"
 
     panels = [
-      PageChooserPanel('page'),
       SnippetChooserPanel('advert', Advert),
     ]
 
     def __unicode__(self):
       return self.page.title + " -> " + self.advert.text
 
-  register_snippet(AdvertPlacement)
+  class BookPage(Page):
+    ...
 
-The class ``AdvertPlacement`` has two properties, ``page`` and ``advert``, which point to other models. Wagtail provides a ``PageChooserPanel`` and ``SnippetChooserPanel`` to let us make painless selection of those properties in the Wagtail admin. Note also the ``Meta`` class, which you can stock with the ``verbose_name`` and ``verbose_name_plural`` properties to override the snippet labels in the Wagtail admin. The text representation of the class has also gotten fancy, using both properties to construct a compound label showing the relationship it forms between a page and an Advert.
+  BookPage.content_panels = [
+    InlinePanel(BookPage, 'advert_placements', label="Adverts"),
+    # ...
+  ]
 
-With this snippet in place, we can use the reverse ``related_name`` lookup label ``advert_placements`` to iterate over any placements within our template files. In the template for a ``Page``-derived model, we could include the following:
+
+These child objects are now accessible through the page's ``advert_placements`` property, and from there we can access the linked Advert snippet as ``advert``. In the template for ``BookPage``, we could include the following:
 
 .. code-block:: django
 
-  {% if self.advert_placements %}
-    {% for advert_placement in self.advert_placements.all %}
-      <p><a href="{{ advert_placement.advert.url }}">{{ advert_placement.advert.text }}</a></p>
-    {% endfor %}
-  {% endif %}
+  {% for advert_placement in self.advert_placements.all %}
+    <p><a href="{{ advert_placement.advert.url }}">{{ advert_placement.advert.text }}</a></p>
+  {% endfor %}
 
 

docs/editor_manual/documents_images_snippets/documents.rst

@@ -3,14 +3,14 @@ Documents
 
 Documents such as PDFs can be managed from the Documents interface, available in the left-hand menu. This interface allows you to add documents to and remove documents from the CMS.
 
-.. image:: ../../images/screen29_documents_page.png
+.. image:: ../../_static/images/screen29_documents_page.png
 
 * Add documents by clicking the *Add document* button in the top-right.
 * Search for documents in the CMS by entering your search term in the search bar. The results will be automatically updated as you type.
 * You can also filter the results by *Popular tags*. Click on a tag to update the search results listing.
 * Edit the details of a document by clicking the document title.
 
-.. image:: ../../images/screen30_documents_edit_page.png
+.. image:: ../../_static/images/screen30_documents_edit_page.png
 
 * When editing a document you can replace the file associated with that document record. This means you can update documents without having to update the pages on which they are placed. Changing the file will change it on all pages that use the document.
 * Add or remove tags using the Tags field.

docs/editor_manual/documents_images_snippets/images.rst

@@ -3,11 +3,11 @@ Images
 
 If you want to edit, add or remove images from the CMS outside of the individual pages you can do so from the Images interface. This is accessed from the left-hand menu.
 
-.. image:: ../../images/screen31_images_page.png
+.. image:: ../../_static/images/screen31_images_page.png
 
 * Clicking an image will allow you to edit the data associated with it. This includes the Alt text, the photographers credit, the medium of the subject matter and much more. **NOTE:** changing the alt text here will alter it for all occurrences of the image in carousels, but not in inline images, where the alt text can be set separately.
 
-.. image:: ../../images/screen32_image_edit_page.png
+.. image:: ../../_static/images/screen32_image_edit_page.png
 
 * When editing an image you can replace the file associated with that image record. This means you can update images without having to update the pages on which they are placed. Changing the file will change it on all pages that use the image.
 

docs/editor_manual/editing_existing_pages.rst

@@ -6,7 +6,7 @@ There are two ways that you can access the edit screen of an existing page:
 * Clicking the title of the page in an `Explorer page <the_explorer_page.html>`_ or in `search results <using_search.html>`_.
 * Clicking the *Edit* link below the title in either of the situations above.
 
-.. image:: ../images/screen12_edit_screen_overview.png
+.. image:: ../_static/images/screen12_edit_screen_overview.png
 
 * When editing an existing page the title of the page being edited is displayed at the top of the page.
 * The current status of the page is displayed in the top-right.

docs/editor_manual/finding_your_way_around/the_dashboard.rst

@@ -11,7 +11,7 @@ The Dashboard provides information on:
 
 You can return to the Dashboard at any time by clicking the Wagtail log in the top-left of the screen.
 
-.. image:: ../../images/screen02_dashboard_editor.png
+.. image:: ../../_static/images/screen02_dashboard_editor.png
 
 - Clicking the logo returns you to your Dashboard.
 - Thes stats at the top of the page describe the total amount of content on the CMS (just for fun!).

docs/editor_manual/finding_your_way_around/the_explorer_menu.rst

@@ -1,7 +1,7 @@
 The Explorer menu
 ~~~~~~~~~~~~~~~~~
 
-.. image:: ../../images/screen03_explorer_menu.png
+.. image:: ../../_static/images/screen03_explorer_menu.png
 
 * Click the Explorer button in the sidebar to open the site explorer. This allows you to navigate through the tree-structure of the site.
 * Clicking the name of a page will take you to the Explorer page for that section (see below). NOTE: The site explorer only displays pages which themselves have child pages. To see and edit the child pages you should click the name of the parent page in the site explorer.

docs/editor_manual/finding_your_way_around/the_explorer_page.rst

@@ -4,20 +4,20 @@ The Explorer page
 The Explorer page allows you to view the a page's children and perform actions on them. From here you can publish/unpublish pages, move pages to other sections, drill down further into the content tree, or reorder pages under the parent for the purposes of display in menus.
 
 
-.. image:: ../../images/screen05_explorer_page.png
+.. image:: ../../_static/images/screen05_explorer_page.png
 
 * The name of the section you are looking at is displayed below the breadcrumb (the row of page names beginning with the home icon). Each section is also itself a page (in this case the homepage). Clicking the title of the section takes you to the Edit screen for the section page.
 * As the heading suggests, below are the child pages of the section. Clicking the titles of each child page will take you to its Edit screen.
 
-.. image:: ../../images/screen06_explorer_page_arrow.png
+.. image:: ../../_static/images/screen06_explorer_page_arrow.png
 
 * Clicking the arrows will display a further level of child pages.
 
-.. image:: ../../images/screen07_explorer_page_breadcrumb.png
+.. image:: ../../_static/images/screen07_explorer_page_breadcrumb.png
 
 * As you drill down through the site the breadcrumb (the row of pages beginning with the home icon) will display the path you have taken. Clicking on the page titles in the breadcrumb will take you to the Explorer screen for that page.
 
-.. image:: ../../images/screen08_add_page_button.png
+.. image:: ../../_static/images/screen08_add_page_button.png
 
 * To add further child pages press the Add child page button below the parent page title. You can view the parent page on the live site by pressing the View live button. The Move button will take you to the Move page screen where you can reposition the page and all its child pages in the site structure.
 * Similar buttons are available for each child page. These are made visible on hover.
@@ -25,7 +25,7 @@ The Explorer page allows you to view the a page's children and perform actions o
 Reordering pages
 ________________
 
-.. image:: ../../images/screen08.5_reorder_page_handles.png
+.. image:: ../../_static/images/screen08.5_reorder_page_handles.png
 
 * Clicking the icon to the far left of the child pages table will enable the reordering handles. This allows you to reorder the way that content displays in the main menu of your website.
 * Reorder by dragging the pages by the handles on the far left (the icon made up of 8 dots).

docs/editor_manual/finding_your_way_around/using_search.rst

@@ -1,7 +1,7 @@
 Using search
 ~~~~~~~~~~~~
 
-.. image:: ../../images/screen04_search_screen.png
+.. image:: ../../_static/images/screen04_search_screen.png
 
 * A very easy way to find the page that you want is to use the main search feature, accessible from the left-hand menu.
 * Simply type in part or all of the name of the page you are looking for, and the results below will automatically update as you type.

docs/editor_manual/getting_started.rst

@@ -15,4 +15,4 @@ __________
 * Access this by adding **/admin** onto the end of your root URL (e.g. www.example.com/admin).
 * Enter your username and password and click **Sign in**.
 
-.. image:: ../images/screen01_login.png
+.. image:: ../_static/images/screen01_login.png

docs/editor_manual/new_pages/adding_multiple_items.rst

@@ -3,15 +3,15 @@ Adding multiple items
 
 A common feature of Wagtail is the ability to add more than one of a particular type of field or item. For example, you can add as many carousel items or related links as you wish.
 
-.. image:: ../../images/screen24_multiple_items_closed.png
+.. image:: ../../_static/images/screen24_multiple_items_closed.png
 
 * Whenever you see the white cross in the green circle illustrated here it means you can add multiple objects or items to a page. Clicking the icon will display the fields required for that piece of content. The image below demonstrates this with a *Related link* item.
 
-.. image:: ../../images/screen25_multiple_items_open.png
+.. image:: ../../_static/images/screen25_multiple_items_open.png
 
 * You can delete an individual item by pressing the trash can in the top-right.
 * You can add more items by clicking the link with the white cross again.
 
-.. image:: ../../images/screen26_reordering_multiple_items.png
+.. image:: ../../_static/images/screen26_reordering_multiple_items.png
 
 4. You can reorder your multiple items using the up and down arrows. Doing this will affect the order in which they are display on the live page.

docs/editor_manual/new_pages/creating_body_content.rst

@@ -7,34 +7,34 @@ There are two types of text entry fields you will see when creating a page. Some
 
 So, when you click into certain fields, for example the *Body* field, you will be presented with a set of tools which allow you to format and style your text. These tools also allow you to insert links, images, videos clips and links to documents.
 
-.. image:: ../../images/screen11_rich_text_field.png
+.. image:: ../../_static/images/screen11_rich_text_field.png
 
 Below is a summary of what the different buttons represent:
 
-.. image:: ../../images/screen11.1_bold_italic.png
+.. image:: ../../_static/images/screen11.1_bold_italic.png
 
 **Bold / Italic:**  Either click then type for bold or italic, or highlight and select to convert existing text to bold or italic.
 
-.. image:: ../../images/screen11.2_formatting_options.png
+.. image:: ../../_static/images/screen11.2_formatting_options.png
 
 **Paragraph / heading levels:**  Clicking into a paragraph and selecting one of these options will change the level of the text. H1 is not included as this is reserved for the page title.
 
-.. image:: ../../images/screen11.3_lists.png
+.. image:: ../../_static/images/screen11.3_lists.png
 
 **Bulleted and numbered lists**
 
-.. image:: ../../images/screen11.4_horizontal_rule.png
+.. image:: ../../_static/images/screen11.4_horizontal_rule.png
 
 **Horizontal rule:** Creates a horizontal line at the position of the cursor. If inserted inside a paragraph it will split the paragraph into two seperate paragraphs.
 
-.. image:: ../../images/screen11.5_undo_redo.png
+.. image:: ../../_static/images/screen11.5_undo_redo.png
 
 **Undo / redo:** As expected will undo or redo the latest actions. Never use the your browser's back button when attempting to undo changes as this could lead to errors. Either use this undo button, or the usual keyboard shortcut, CTRL+Z.
 
-.. image:: ../../images/screen11.6_images_videos.png
+.. image:: ../../_static/images/screen11.6_images_videos.png
 
-**Insert image / video:** Allows you to insert an image or video into the rich text field. See Inserting images and videos section for more details. .. insert links for images and videos here>>
+**Insert image / video:** Allows you to insert an image or video into the rich text field. See Inserting images and videos section for more details. See `Inserting images <inserting_images.html>` and `Inserting videos <inserting_videos.html>` sections.
 
-.. image:: ../../images/screen11.7_links_docs.png
+.. image:: ../../_static/images/screen11.7_links_docs.png
 
-**Insert link / document:** Allows you to insert a link or a document into the rich text field. See Inserting links and Inserting documents for more details. .. insert links to Links and documents sections>>
+**Insert link / document:** Allows you to insert a link or a document into the rich text field. See Inserting links and Inserting documents for more details. See `Inserting links section <inserting_links.html>`.

docs/editor_manual/new_pages/index.rst

@@ -1,7 +1,7 @@
 Creating new pages
 ~~~~~~~~~~~~~~~~~~
 
-.. image:: ../../images/screen08_add_page_button.png
+.. image:: ../../_static/images/screen08_add_page_button.png
 
 Create new pages by clicking the Add child page. This creates a child page of the section you are currently in. In this case a child page of the Homepage.
 

docs/editor_manual/new_pages/inserting_documents.rst

@@ -1,10 +1,10 @@
 Inserting links to documents into body text
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. image:: ../../images/screen27_docs_icon.png
+.. image:: ../../_static/images/screen27_docs_icon.png
 
 It is possible to insert links to documents held in the CMS into the body text of a web page by clicking the button above in the Body field.
 
 The process for doing this is the same as when inserting an image. You are given the choice of either choosing a document from the CMS, or uploading a new document.
 
-.. image:: ../../images/screen28_docs_form.png
+.. image:: ../../_static/images/screen28_docs_form.png

docs/editor_manual/new_pages/inserting_images.rst

@@ -11,11 +11,11 @@ __________________________________
 
 The carousel is where the main, featured images and videos associated with a page should be displayed.
 
-.. image:: ../../images/screen14_add_carousel_button.png
+.. image:: ../../_static/images/screen14_add_carousel_button.png
 
 * To insert a carousel item click the Add carousel content link in the Carousel content section.
 
-.. image:: ../../images/screen15_carousel_form.png
+.. image:: ../../_static/images/screen15_carousel_form.png
 
 * You can then insert an image by clicking the *Choose an image* button.
 * It is also possible to add videos to a carousel. Simply copy and paste the web address for the video (either YouTube or Vimeo) into the *Embed URL* field and click Insert. A poster image for the video can also be uploaded or selected from the CMS. This is the image displayed before a user has clicked play on the video.
@@ -38,7 +38,7 @@ When you click the *Choose an image* button you will be presented with a pop-up
 
 The image below demonstrates finding and  inserting an image that is already present in the CMS image library.
 
-.. image:: ../../images/screen16_selecting_image_from_library.png
+.. image:: ../../_static/images/screen16_selecting_image_from_library.png
 
 #. Typing into the search box will automatically display the results below.
 #. Clicking one of the Popular tags will filter the search results by that tag.
@@ -46,7 +46,7 @@ The image below demonstrates finding and  inserting an image that is already pre
 
 **Uploading a new image to the CMS**
 
-.. image:: ../../images/screen17_upload_image.png
+.. image:: ../../_static/images/screen17_upload_image.png
 
 #. You must include an image title for your uploaded image
 #. Click the *Choose file* button to choose an image from your computer.
@@ -60,12 +60,12 @@ Images can also be inserted into the body text of a page. When editing the Body
 
 In addition, the Wagtail Demo site allows you to chose an aligmnent for you image.
 
-.. image:: ../../images/screen18_image_alignment.png
+.. image:: ../../_static/images/screen18_image_alignment.png
 
 #. You can select how the image is displayed by selecting one of the format options.
 #. In the Wagtail Demo site, images inserted into the body text do not have embeded captions (these should be added as regular body text). However you must still provide specific alt text for your image.
 
-The aligmnents available are described below:
+The alignments available are described below:
 
 * **Full width:** Image will be inserted using the full width of the text area.
 * **Half-width left/right aligned:** Inserts the image at half the width of the text area. If inserted in a block of text the text will wrap around the image. If two half-width images are inserted together they will display next to each other.

docs/editor_manual/new_pages/inserting_links.rst

@@ -5,7 +5,7 @@ Similar to images, there are a variety of points at which you will want to add l
 
 Whichever way you insert a link, you will be presented with the form displayed below.
 
-.. image:: ../../images/screen19_link_form.png
+.. image:: ../../_static/images/screen19_link_form.png
 
 * Search for an existing page to link to using the search bar at the top of the pop-up.
 * Below the search bar you can select the type of link you want to insert. The following types are available:

docs/editor_manual/new_pages/inserting_videos.rst

@@ -6,10 +6,10 @@ Inserting videos into body content
 
 As well as inserting videos into a carousel, Wagtail's rich text fields allow you to add videos into the body of a page by clicking the *Add video* button in the toolbar.
 
-.. image:: ../../images/screen20_insert_video_form.png	
+.. image:: ../../_static/images/screen20_insert_video_form.png	
 
 * Copy and paste the web address for the video (either YouTube or Vimeo) into the URL field and click Insert.
 
-.. image:: ../../images/screen21_video_in_editor.png	
+.. image:: ../../_static/images/screen21_video_in_editor.png	
 
 * A placeholder with the name of the video and a screenshot will be inserted into the text area. Clicking the X in the top corner will remove the video.

docs/editor_manual/new_pages/previewing_and_submitting_for_moderation.rst

@@ -9,4 +9,4 @@ The Save/Preview/Submit for moderation menu is always present at the bottom of t
 * **Publish/Unpublish:** Clicking either the *Publish* or *Unpublish* buttons will take you to a confirmation screen asking you to confirm that you wish to publish or unpublish this page. If a page is published it will be accessible from its specific URL and will also be displayed in site search results. (moderators and administrators only)
 * **Delete:** Clicking this button will take you to a confirmation screen asking you to confirm that you wish to delete the current page. Be sure that this is actually what you want to do, as deleted pages are not recoverable. In many situations simply unpublishing the page will be enough. (moderators and administrators only)
 
-.. image:: ../../images/screen13_publish_menu.png
+.. image:: ../../_static/images/screen13_publish_menu.png

docs/editor_manual/new_pages/required_fields.rst

@@ -3,9 +3,9 @@ Required fields
 
 * Fields marked with an asterisk are required. You will not be able to save a draft or submit the page for moderation without these fields being completed.
 
-..  image:: ../../images/screen22_required_field.png
+..  image:: ../../_static/images/screen22_required_field.png
 
 * If you try to save/submit the page with some required fields not filled out, you will see the error displayed here.
 * The number of validation errors for each of the *Promote* and *Content* tabs will appear in a red circle, and the text, 'This field is required', will appear below each field that must be completed.
 
-..  image:: ../../images/screen23_validation_error.png
+..  image:: ../../_static/images/screen23_validation_error.png

docs/editor_manual/new_pages/selecting_a_page_type.rst

@@ -1,12 +1,12 @@
 Selecting a page type
 ~~~~~~~~~~~~~~~~~~~~~
 
-.. image:: ../../images/screen09_page_type_selection.png
+.. image:: ../../_static/images/screen09_page_type_selection.png
 
 * On the left of the page chooser screen are listed all the types of pages that you can create. Clicking the page type name will take you to the Create new page screen for that page type (see below).
 * Clicking the *View all … pages* links on the right will display all the pages that exist on the website of this type. This is to help you judge what type of page you will need to complete your task.
 
-.. image:: ../../images/screen10_blank_page_edit_screen.png
+.. image:: ../../_static/images/screen10_blank_page_edit_screen.png
 
 * Once you’ve selected a page type you will be presented with a blank New page screen.
 * Click into the areas below each field's heading to start entering content.

docs/howto/deploying.rst

@@ -4,7 +4,7 @@ Deploying Wagtail
 On your server
 ~~~~~~~~~~~~~~
 
-Wagtail is straightforward to deploy on modern Linux-based distributions, but see the section on :doc:`performance </performance>` for the non-Python services we recommend. If you are running Debian or Ubuntu, this installation script for our Vagrant box may be useful:
+Wagtail is straightforward to deploy on modern Linux-based distributions, but see the section on :doc:`performance </howto/performance>` for the non-Python services we recommend. If you are running Debian or Ubuntu, this installation script for our Vagrant box may be useful:
 
 `github.com/torchbox/wagtaildemo/blob/master/etc/install/install.sh <https://github.com/torchbox/wagtaildemo/blob/master/etc/install/install.sh>`_
 
@@ -18,4 +18,4 @@ On Gondor
 On other PAASs and IAASs
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-We know of Wagtail sites running on `Heroku <http://spapas.github.io/2014/02/13/wagtail-tutorial/>`_, Digital Ocean and elsewhere. If you have successfully installed Wagtail on your platform or infrastructure, please :doc:`contribute </contributing>` your notes to this documentation!
+We know of Wagtail sites running on `Heroku <http://spapas.github.io/2014/02/13/wagtail-tutorial/>`_, Digital Ocean and elsewhere. If you have successfully installed Wagtail on your platform or infrastructure, please :doc:`contribute </howto/contributing>` your notes to this documentation!

docs/howto/index.rst

@@ -0,0 +1,11 @@
+How to
+======
+
+
+.. toctree::
+    :maxdepth: 2
+
+    settings
+    deploying
+    performance
+    contributing

docs/howto/settings.rst

@@ -141,7 +141,7 @@ Wagtail Apps
   Search framework for Page content. See :ref:`search`.
 
 ``wagtailredirects``
-  Admin interface for creating arbitrary redirects on your site. See :ref:`redirects`.
+  Admin interface for creating arbitrary redirects on your site.
 
 ``wagtailforms``
   Models for creating forms on your pages and viewing submissions. See :ref:`form_builder`.