Use .. code-block:: for all python, html blocks

docs/advanced_topics/performance.rst

@@ -13,7 +13,9 @@ We have tried to minimise external dependencies for a working installation of Wa
 Cache
 -----
 
-We recommend `Redis <http://redis.io/>`_ as a fast, persistent cache. Install Redis through your package manager (on Debian or Ubuntu: ``sudo apt-get install redis-server``), add ``django-redis`` to your ``requirements.txt``, and enable it as a cache backend::
+We recommend `Redis <http://redis.io/>`_ as a fast, persistent cache. Install Redis through your package manager (on Debian or Ubuntu: ``sudo apt-get install redis-server``), add ``django-redis`` to your ``requirements.txt``, and enable it as a cache backend:
+
+.. code-block:: python
 
 	CACHES = {
 	    'default': {
@@ -33,9 +35,9 @@ Wagtail has strong support for `Elasticsearch <http://www.elasticsearch.org/>`_
 
 Once the Elasticsearch server is installed and running. Install the ``elasticsearch`` Python module with::
 
-    pip install elasticsearch
+then add the following to your settings:
 
-then add the following to your settings::
+.. code-block:: python
 
     WAGTAILSEARCH_BACKENDS = {
         'default': {
@@ -58,7 +60,9 @@ Wagtail is tested on SQLite, and should work on other Django-supported database
 Templates
 ---------
 
-The overhead from reading and compiling templates can add up. In some cases a significant performance improvement can be gained by using `Django's cached template loader <https://docs.djangoproject.com/en/1.10/ref/templates/api/#django.template.loaders.cached.Loader>`_::
+The overhead from reading and compiling templates can add up. In some cases a significant performance improvement can be gained by using `Django's cached template loader <https://docs.djangoproject.com/en/1.10/ref/templates/api/#django.template.loaders.cached.Loader>`_:
+
+.. code-block:: python
 
     TEMPLATES = [{
         'BACKEND': 'django.template.backends.django.DjangoTemplates',

docs/getting_started/integrating_into_django.rst

@@ -5,16 +5,20 @@ Integrating Wagtail into a Django project
 
 Wagtail provides the ``wagtail start`` command and project template to get you started with a new Wagtail project as quickly as possible, but it's easy to integrate Wagtail into an existing Django project too.
 
-Wagtail is currently compatible with Django 1.8, 1.9 and 1.10. First, install the ``wagtail`` package from PyPI::
+Wagtail is currently compatible with Django 1.8, 1.9 and 1.10. First, install the ``wagtail`` package from PyPI:
 
-    pip install wagtail
+.. code-block:: console
+
+    $ pip install wagtail
 
 or add the package to your existing requirements file. This will also install the **Pillow** library as a dependency, which requires libjpeg and zlib - see Pillow's `platform-specific installation instructions <http://pillow.readthedocs.org/en/latest/installation.html#external-libraries>`_.
 
 Settings
 --------
 
-In your settings file, add the following apps to ``INSTALLED_APPS``::
+In your settings file, add the following apps to ``INSTALLED_APPS``:
+
+.. code-block:: python
 
     'wagtail.wagtailforms',
     'wagtail.wagtailredirects',
@@ -31,7 +35,9 @@ In your settings file, add the following apps to ``INSTALLED_APPS``::
     'modelcluster',
     'taggit',
 
-Add the following entries to ``MIDDLEWARE_CLASSES``::
+Add the following entries to ``MIDDLEWARE_CLASSES``:
+
+.. code-block:: python
 
     'wagtail.wagtailcore.middleware.SiteMiddleware',
     'wagtail.wagtailredirects.middleware.RedirectMiddleware',
@@ -75,7 +81,9 @@ The URL paths here can be altered as necessary to fit your project's URL scheme.
 
 ``wagtaildocs_urls`` is the location from where document files will be served. This can be omitted if you do not intend to use Wagtail's document management features.
 
-``wagtail_urls`` is the base location from where the pages of your Wagtail site will be served. In the above example, Wagtail will handle URLs under ``/pages/``, leaving the root URL and other paths to be handled as normal by your Django project. If you want Wagtail to handle the entire URL space including the root URL, this can be replaced with::
+``wagtail_urls`` is the base location from where the pages of your Wagtail site will be served. In the above example, Wagtail will handle URLs under ``/pages/``, leaving the root URL and other paths to be handled as normal by your Django project. If you want Wagtail to handle the entire URL space including the root URL, this can be replaced with:
+
+.. code-block:: python
 
     url(r'', include(wagtail_urls)),
 

docs/releases/0.7.rst

@@ -70,7 +70,9 @@ Upgrade considerations
 Addition of ``wagtailsites`` app
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The Sites administration interface is contained within a new app, ``wagtailsites``. To enable this on an existing Wagtail project, add the line::
+The Sites administration interface is contained within a new app, ``wagtailsites``. To enable this on an existing Wagtail project, add the line:
+
+.. code-block:: python
 
     'wagtail.wagtailsites',
 

docs/releases/0.8.rst

@@ -72,18 +72,24 @@ This change shouldn't affect most people as ``SearchResults`` behaves very simil
 Removal of validate_image_format from custom image model migrations (Django 1.7+)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If your project is running on Django 1.7, and you have defined a custom image model (by extending the ``wagtailimages.AbstractImage`` class), the migration that creates this model will probably have a reference to ``wagtail.wagtailimages.utils.validators.validate_image_format``. This module has now been removed, which will cause ``manage.py migrate`` to fail with an ``ImportError`` (even if the migration has already been applied). You will need to edit the migration file to remove the line::
+If your project is running on Django 1.7, and you have defined a custom image model (by extending the ``wagtailimages.AbstractImage`` class), the migration that creates this model will probably have a reference to ``wagtail.wagtailimages.utils.validators.validate_image_format``. This module has now been removed, which will cause ``manage.py migrate`` to fail with an ``ImportError`` (even if the migration has already been applied). You will need to edit the migration file to remove the line:
+
+.. code-block:: python
 
     import wagtail.wagtailimages.utils.validators
 
-and the ``validators`` attribute of the 'file' field - that is, the line::
+and the ``validators`` attribute of the 'file' field - that is, the line:
+
+.. code-block:: python
 
     ('file', models.ImageField(upload_to=wagtail.wagtailimages.models.get_upload_to,
         width_field='width', height_field='height',
         validators=[wagtail.wagtailimages.utils.validators.validate_image_format],
         verbose_name='File')),
 
-should become::
+should become:
+
+    .. code-block:: python
 
     ('file', models.ImageField(upload_to=wagtail.wagtailimages.models.get_upload_to,
         width_field='width', height_field='height', verbose_name='File')),

docs/releases/1.0.rst

@@ -153,18 +153,24 @@ If you are upgrading from Elasticsearch 0.90.x, you may also need to update the
 Wagtail version upgrade notifications are enabled by default
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Starting from Wagtail 1.0, the admin dashboard will (for admin users only) perform a check to see if newer releases are available. This also provides the Wagtail team with the hostname of your Wagtail site. If you’d rather not receive update notifications, or if you’d like your site to remain unknown, you can disable it by adding this line to your settings file::
+Starting from Wagtail 1.0, the admin dashboard will (for admin users only) perform a check to see if newer releases are available. This also provides the Wagtail team with the hostname of your Wagtail site. If you’d rather not receive update notifications, or if you’d like your site to remain unknown, you can disable it by adding this line to your settings file:
+
+.. code-block:: python
 
     WAGTAIL_ENABLE_UPDATE_CHECK = False
 
 ``InlinePanel`` definitions no longer need to specify the base model
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In previous versions of Wagtail, inline child blocks on a page or snippet were defined using a declaration like::
+In previous versions of Wagtail, inline child blocks on a page or snippet were defined using a declaration like:
+
+.. code-block:: python
 
     InlinePanel(HomePage, 'carousel_items', label="Carousel items")
 
-It is no longer necessary to pass the base model as a parameter, so this declaration should be changed to::
+It is no longer necessary to pass the base model as a parameter, so this declaration should be changed to:
+
+.. code-block:: python
 
     InlinePanel('carousel_items', label="Carousel items")
 
@@ -207,11 +213,15 @@ If you were previously using the external ``wagtailapi`` module (which has now b
 **1. Representation of foreign keys has changed**
 
 Foreign keys were previously represented by just the value of their primary key.
-For example::
+For example:
+
+.. code-block:: python
 
     "feed_image": 1
 
-This has now been changed to add some ``meta`` information::
+This has now been changed to add some ``meta`` information:
+
+.. code-block:: python
 
     "feed_image": {
         "id": 1,
@@ -225,7 +235,9 @@ This has now been changed to add some ``meta`` information::
 **2. On the page detail view, the "parent" field has been moved out of meta**
 
 Previously, there was a "parent" field in the "meta" section on the page detail
-view::
+view:
+
+.. code-block:: python
 
     {
         "id": 10,
@@ -239,7 +251,9 @@ view::
 
 
 This has now been moved to the top level. Also, the above change to how foreign
-keys are represented applies to this field too::
+keys are represented applies to this field too:
+
+.. code-block:: python
 
     {
         "id": 10,
@@ -308,7 +322,9 @@ Previously, the ``document_served`` signal (which is fired whenever a user downl
 Custom image models must specify an ``admin_form_fields`` list
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Previously, the forms for creating and editing images followed Django's default behaviour of showing all fields defined on the model; this would include any custom fields specific to your project that you defined by subclassing ``AbstractImage`` and setting ``WAGTAILIMAGES_IMAGE_MODEL``. This behaviour is risky as it may lead to fields being unintentionally exposed to the user, and so Django has deprecated this, for removal in Django 1.8. Accordingly, if you create your own custom subclass of ``AbstractImage``, you must now provide an ``admin_form_fields`` property, listing the fields that should appear on the image creation / editing form - for example::
+Previously, the forms for creating and editing images followed Django's default behaviour of showing all fields defined on the model; this would include any custom fields specific to your project that you defined by subclassing ``AbstractImage`` and setting ``WAGTAILIMAGES_IMAGE_MODEL``. This behaviour is risky as it may lead to fields being unintentionally exposed to the user, and so Django has deprecated this, for removal in Django 1.8. Accordingly, if you create your own custom subclass of ``AbstractImage``, you must now provide an ``admin_form_fields`` property, listing the fields that should appear on the image creation / editing form - for example:
+
+.. code-block:: python
 
     from wagtail.wagtailimages.models import AbstractImage, Image
 

docs/releases/1.7.rst

@@ -111,16 +111,20 @@ The data model for image renditions will be changed in Wagtail 1.8 to eliminate
 
  * Run ``manage.py makemigrations`` to create the schema migration
  * Run ``manage.py makemigrations --empty myapp`` (replacing ``myapp`` with the name of the app containing the custom image model) to create an empty migration
- * Edit the created migration to contain::
+ * Edit the created migration to contain:
 
-    from wagtail.wagtailimages.utils import get_fill_filter_spec_migrations
+   .. code-block:: python
 
-   and, for the ``operations`` list::
+       from wagtail.wagtailimages.utils import get_fill_filter_spec_migrations
 
-    forward, reverse = get_fill_filter_spec_migrations('myapp', 'CustomRendition')
-    operations = [
-        migrations.RunPython(forward, reverse),
-    ]
+   and, for the ``operations`` list:
+
+   .. code-block:: python
+
+       forward, reverse = get_fill_filter_spec_migrations('myapp', 'CustomRendition')
+       operations = [
+           migrations.RunPython(forward, reverse),
+       ]
 
    replacing ``myapp`` and ``CustomRendition`` with the app and model name for the custom rendition model.
 

docs/topics/images.rst

@@ -5,7 +5,9 @@ Using images in templates
 
 The ``image`` tag inserts an XHTML-compatible ``img`` element into the page, setting its ``src``, ``width``, ``height`` and ``alt``. See also :ref:`image_tag_alt`.
 
-The syntax for the tag is thus::
+The syntax for the tag is thus:
+
+.. code-block:: html+django
 
     {% image [image] [resize-rule] %}
 

docs/topics/permissions.rst

@@ -12,17 +12,12 @@ Page permissions
 
 Permissions can be attached at any point in the page tree, and propagate down the tree. For example, if a site had the page tree::
 
-    MegaCorp
-     |
-     |-- About us
-     |
-      -- Offices
-         |
-         |- UK
-         |
-         |- France
-         |
-         |- Germany
+    MegaCorp/
+        About us
+        Offices/
+            UK
+            France
+            Germany
 
 then a group with 'edit' permissions on the 'Offices' page would automatically receive the ability to edit the 'UK', 'France' and 'Germany' pages. Permissions can be set globally for the entire tree by assigning them on the 'root' page - since all pages must exist underneath the root node, and the root cannot be deleted, this permission will cover all pages that exist now and in future.
 

docs/topics/writing_templates.rst

@@ -85,7 +85,9 @@ Images (tag)
 
 The ``image`` tag inserts an XHTML-compatible ``img`` element into the page, setting its ``src``, ``width``, ``height`` and ``alt``. See also :ref:`image_tag_alt`.
 
-The syntax for the ``image`` tag is thus::
+The syntax for the ``image`` tag is thus:
+
+.. code-block:: html+django
 
     {% image [image] [resize-rule] %}