diff --git a/docs/advanced_topics/images/feature_detection.rst b/docs/advanced_topics/images/feature_detection.rst
index 491f7309f..a9955a332 100644
--- a/docs/advanced_topics/images/feature_detection.rst
+++ b/docs/advanced_topics/images/feature_detection.rst
@@ -19,9 +19,9 @@ Installing OpenCV on Debian/Ubuntu
Debian and ubuntu provide an apt-get package called ``python-opencv``:
- .. code-block:: sh
+ .. code-block:: console
- sudo apt-get install python-opencv python-numpy
+ $ 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.
diff --git a/docs/advanced_topics/performance.rst b/docs/advanced_topics/performance.rst
index 284572dd7..00b4b6233 100644
--- a/docs/advanced_topics/performance.rst
+++ b/docs/advanced_topics/performance.rst
@@ -33,7 +33,11 @@ Search
Wagtail has strong support for `Elasticsearch `_ - both in the editor interface and for users of your site - but can fall back to a database search if Elasticsearch isn't present. Elasticsearch is faster and more powerful than the Django ORM for text search, so we recommend installing it or using a hosted service like `Searchly `_.
-Once the Elasticsearch server is installed and running. Install the ``elasticsearch`` Python module with::
+Once the Elasticsearch server is installed and running. Install the ``elasticsearch`` Python module with:
+
+.. code-block:: console
+
+ $ pip install elasticsearch
then add the following to your settings:
@@ -46,9 +50,11 @@ then add the following to your settings:
},
}
-Once Elasticsearch is configured, you can index any existing content you may have::
+Once Elasticsearch is configured, you can index any existing content you may have:
- ./manage.py update_index
+.. code-block:: console
+
+ $ ./manage.py update_index
Database
diff --git a/docs/advanced_topics/settings.rst b/docs/advanced_topics/settings.rst
index 3dc7d9ba4..d89feb0aa 100644
--- a/docs/advanced_topics/settings.rst
+++ b/docs/advanced_topics/settings.rst
@@ -225,9 +225,9 @@ Providing an API key for the Embedly service will use that as a embed backend, w
To use Embedly, you must also install their Python module:
-.. code-block:: sh
+.. code-block:: console
- pip install embedly
+ $ pip install embedly
Images
diff --git a/docs/contributing/committing.rst b/docs/contributing/committing.rst
index 545317c30..d00f452cb 100644
--- a/docs/contributing/committing.rst
+++ b/docs/contributing/committing.rst
@@ -10,8 +10,8 @@ by at least one other reviewer or committer,
unless the change is a small documentation change or fixing a typo.
Most code contributions will be in the form of pull requests from Github.
-Pull requests should not be merged from Github, apart from small documentation fixes,
-which can be merged with the 'Squash and merge' option. Instead, the code should
+Pull requests should not be merged from Github, apart from small documentation fixes,
+which can be merged with the 'Squash and merge' option. Instead, the code should
be checked out by a committer locally, the changes examined and rebased,
the ``CHANGELOG.txt`` and release notes updated,
and finally the code should be pushed to the master branch.
@@ -42,16 +42,16 @@ You can fix up any small mistakes in the commits,
such as typos and formatting, as part of the rebase.
``git rebase --interactive`` is an excellent tool for this job.
-.. code-block:: sh
+.. code-block:: console
- # Get the latest commits from Wagtail
+ $ # Get the latest commits from Wagtail
$ git fetch upstream
$ git checkout master
$ git merge --ff-only upstream/master
- # Rebase this pull request on to master
+ $ # Rebase this pull request on to master
$ git checkout pr/xxxx
$ git rebase master
- # Update master to this commit
+ $ # Update master to this commit
$ git checkout master
$ git merge --ff-only pr/xxxx
@@ -92,7 +92,7 @@ If the changes to be merged are small enough to be a single commit,
amend this single commit with the additions to
the ``CHANGELOG.txt``, release notes, and contributors:
-.. code-block:: sh
+.. code-block:: console
$ git add CHANGELOG.txt docs/releases/x.x.x.rst CONTRIBUTORS.rst
$ git commit --amend --no-edit
@@ -101,7 +101,7 @@ If the changes do not fit in a single commit, make a new commit with the updates
the ``CHANGELOG.txt``, release notes, and contributors.
The commit message should say ``Release notes for #xxxx``:
-.. code-block:: sh
+.. code-block:: console
$ git add CHANGELOG.txt docs/releases/x.x.x.rst CONTRIBUTORS.rst
$ git commit -m 'Release notes for #xxxx'
@@ -111,11 +111,11 @@ Push to master
The changes are ready to be pushed to ``master`` now.
-.. code-block:: sh
+.. code-block:: console
- # Check that everything looks OK
+ $ # Check that everything looks OK
$ git log upstream/master..master --oneline
$ git push --dry-run upstream master
- # Push the commits!
+ $ # Push the commits!
$ git push upstream master
$ git branch -d pr/xxxx
diff --git a/docs/contributing/css_guidelines.rst b/docs/contributing/css_guidelines.rst
index 0fd0d7d5b..360229aa5 100644
--- a/docs/contributing/css_guidelines.rst
+++ b/docs/contributing/css_guidelines.rst
@@ -12,14 +12,14 @@ This requires `node.js `_ to run.
To install the libraries required for compiling the SCSS,
run the following from the Wagtail repository root:
-.. code-block:: bash
+.. code-block:: console
$ npm install
To compile the assets, run:
-.. code-block:: bash
+.. code-block:: console
$ npm run build
@@ -27,7 +27,7 @@ To compile the assets, run:
Alternatively, the SCSS files can be monitored,
automatically recompiling when any changes are observed, by running:
-.. code-block:: bash
+.. code-block:: console
$ npm start
@@ -39,14 +39,14 @@ Wagtail uses the "scss-lint" Ruby Gem for linting.
Install it thus:
-.. code-block:: bash
+.. code-block:: console
$ gem install scss-lint
Then run the linter from the wagtail project root:
-.. code-block:: bash
+.. code-block:: console
$ scss-lint
diff --git a/docs/contributing/developing.rst b/docs/contributing/developing.rst
index 5c62348ed..fe8786e6d 100644
--- a/docs/contributing/developing.rst
+++ b/docs/contributing/developing.rst
@@ -19,28 +19,28 @@ Install Node.js, v5.3.0 or higher. Instructions for installing Node.js can be fo
Clone a copy of `the Wagtail codebase `_:
-.. code-block:: sh
+.. code-block:: console
- git clone https://github.com/torchbox/wagtail.git
- cd wagtail
+ $ git clone https://github.com/torchbox/wagtail.git
+ $ cd wagtail
With your preferred virtualenv activated, install the Wagtail package in development mode with the included testing and documentation dependencies:
-.. code-block:: sh
+.. code-block:: console
- pip install -e .[testing,docs] -U
+ $ pip install -e .[testing,docs] -U
Install the tool chain for building static assets:
-.. code-block:: sh
+.. code-block:: console
- npm install
+ $ npm install
Compile the assets:
-.. code-block:: sh
+.. code-block:: console
- npm run build
+ $ npm run build
Any Wagtail sites you start up in this virtualenv will now run against this development instance of Wagtail. We recommend using the `Wagtail demo site `_ as a basis for developing Wagtail.
@@ -49,33 +49,41 @@ Any Wagtail sites you start up in this virtualenv will now run against this deve
Testing
~~~~~~~
-From the root of the Wagtail codebase, run the following command to run all the tests::
+From the root of the Wagtail codebase, run the following command to run all the tests:
- python runtests.py
+.. code-block:: console
+
+ $ python runtests.py
**Running only some of the tests**
At the time of writing, Wagtail has well over 1000 tests, which takes a while to
run. You can run tests for only one part of Wagtail by passing in the path as
-an argument to ``runtests.py``::
+an argument to ``runtests.py``:
- python runtests.py wagtail.wagtailcore
+.. code-block:: console
+
+ $ python runtests.py wagtail.wagtailcore
**Testing against PostgreSQL**
By default, Wagtail tests against SQLite. You can switch to using PostgreSQL by
-using the ``--postgres`` argument::
+using the ``--postgres`` argument:
- python runtests.py --postgres
+.. code-block:: console
+
+ $ python runtests.py --postgres
If you need to use a different user, password or host. Use the ``PGUSER``, ``PGPASSWORD`` and ``PGHOST`` environment variables.
**Testing against a different database**
If you need to test against a different database, set the ``DATABASE_ENGINE``
-environment variable to the name of the Django database backend to test against::
+environment variable to the name of the Django database backend to test against:
- DATABASE_ENGINE=django.db.backends.mysql python runtests.py
+.. code-block:: console
+
+ $ DATABASE_ENGINE=django.db.backends.mysql python runtests.py
This will create a new database called ``test_wagtail`` in MySQL and run
the tests against it.
@@ -83,18 +91,22 @@ the tests against it.
**Testing Elasticsearch**
You can test Wagtail against Elasticsearch by passing the ``--elasticsearch``
-argument to ``runtests.py``::
+argument to ``runtests.py``:
- python runtests.py --elasticsearch
+.. code-block:: console
+
+ $ python runtests.py --elasticsearch
Wagtail will attempt to connect to a local instance of Elasticsearch
(``http://localhost:9200``) and use the index ``test_wagtail``.
If your Elasticsearch instance is located somewhere else, you can set the
-``ELASTICSEARCH_URL`` environment variable to point to its location::
+``ELASTICSEARCH_URL`` environment variable to point to its location:
- ELASTICSEARCH_URL=http://my-elasticsearch-instance:9200 python runtests.py --elasticsearch
+.. code-block:: console
+
+ $ ELASTICSEARCH_URL=http://my-elasticsearch-instance:9200 python runtests.py --elasticsearch
Compiling static assets
~~~~~~~~~~~~~~~~~~~~~~~
@@ -103,41 +115,41 @@ All static assets such as JavaScript, CSS, images, and fonts for the Wagtail adm
To compile the assets, run:
-.. code-block:: sh
+.. code-block:: console
- npm run build
+ $ npm run build
This must be done after every change to the source files. To watch the source files for changes and then automatically recompile the assets, run:
-.. code-block:: sh
+.. code-block:: console
- npm start
+ $ npm start
Compiling the documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Wagtail documentation is built by Sphinx. To install Sphinx and compile the documentation, run:
-.. code-block:: sh
+.. code-block:: console
- cd /path/to/wagtail
- # Install the documentation dependencies
- pip install -e .[docs]
- # Compile the docs
- cd docs/
- make html
+ $ cd /path/to/wagtail some text
+ $ # Install the documentation dependencies
+ $ pip install -e .[docs]
+ $ # Compile the docs
+ $ cd docs/
+ $ make html
The compiled documentation will now be in ``docs/_build/html``.
Open this directory in a web browser to see it.
Python comes with a module that makes it very easy to preview static files in a web browser.
To start this simple server, run the following commands:
-.. code-block:: sh
+.. code-block:: console
$ cd docs/_build/html/
- # Python 2
+ $ # Python 2
$ python2 -mSimpleHTTPServer 8080
- # Python 3
+ $ # Python 3
$ python3 -mhttp.server 8080
Now you can open in your web browser to see the compiled documentation.
@@ -146,7 +158,7 @@ Sphinx caches the built documentation to speed up subsequent compilations.
Unfortunately, this cache also hides any warnings thrown by unmodified documentation source files.
To clear the built HTML and start fresh, so you can see all warnings thrown when building the documentation, run:
-.. code-block:: sh
+.. code-block:: console
$ cd docs/
$ make clean
diff --git a/docs/contributing/javascript_guidelines.rst b/docs/contributing/javascript_guidelines.rst
index cfff48463..0e9fb31a3 100644
--- a/docs/contributing/javascript_guidelines.rst
+++ b/docs/contributing/javascript_guidelines.rst
@@ -17,10 +17,12 @@ Wagtail provides some tooling configuration to help check your code meets the
styleguide. You'll need node.js and npm on your development machine.
Ensure project dependencies are installed by running ``npm install``
+Linting code
+------------
-**Linting code**
+.. code-block:: console
-``npm run lint:js``
+ $ npm run lint:js
This will lint all the JS in the wagtail project, excluding vendor
files and compiled libraries.
@@ -29,10 +31,12 @@ Some of the modals are generated via server-side scripts. These include
template tags that upset the linter, so modal workflow JavaScript is
excluded from the linter.
+Formatting code
+---------------
-**Formatting code**
+.. code-block:: console
-``npm run format:js``
+ $ npm run format:js
This will perform safe edits to conform your JS code to the styleguide.
It won't touch the line-length, or convert quotemarks from double to single.
@@ -40,7 +44,8 @@ It won't touch the line-length, or convert quotemarks from double to single.
Run the linter after you've formatted the code to see what manual fixes
you need to make to the codebase.
-**Changing the linter configuration**
+Changing the linter configuration
+---------------------------------
Under the hood, the tasks use the `JavaScript Code Style `_ library.
diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst
index add61ad34..93d703a3d 100644
--- a/docs/getting_started/index.rst
+++ b/docs/getting_started/index.rst
@@ -14,24 +14,30 @@ We'd also recommend Virtualenv, which provides isolated Python environments:
.. important::
Before installing Wagtail, it is necessary to install the **libjpeg** and **zlib** libraries, which provide support for working with JPEG, PNG and GIF images (via the Python **Pillow** library). The way to do this varies by platform - see Pillow's `platform-specific installation instructions `_.
-With the above installed, the quickest way to install Wagtail is::
+With the above installed, the quickest way to install Wagtail is:
- pip install wagtail
+.. code-block:: console
+
+ $ pip install wagtail
(``sudo`` may be required if installing system-wide or without virtualenv)
-Once installed, Wagtail provides a command similar to Django's ``django-admin startproject`` which stubs out a new site/project::
+Once installed, Wagtail provides a command similar to Django's ``django-admin startproject`` which stubs out a new site/project:
- wagtail start mysite
+.. code-block:: console
+
+ $ wagtail start mysite
This will create a new folder ``mysite``, based on a template containing all you need to get started. More information on that template is available :doc:`here `.
-Inside your ``mysite`` folder, we now just run the setup steps necessary for any Django project::
+Inside your ``mysite`` folder, we now just run the setup steps necessary for any Django project:
- pip install -r requirements.txt
- ./manage.py migrate
- ./manage.py createsuperuser
- ./manage.py runserver
+.. code-block:: console
+
+ $ pip install -r requirements.txt
+ $ ./manage.py migrate
+ $ ./manage.py createsuperuser
+ $ ./manage.py runserver
Your site is now accessible at ``http://localhost:8000``, with the admin backend available at ``http://localhost:8000/admin/``.
diff --git a/docs/getting_started/tutorial.rst b/docs/getting_started/tutorial.rst
index 261676341..fafbcec25 100644
--- a/docs/getting_started/tutorial.rst
+++ b/docs/getting_started/tutorial.rst
@@ -4,14 +4,18 @@ Your first Wagtail site
.. note::
This tutorial covers setting up a brand new Wagtail project. If you'd like to add Wagtail to an existing Django project instead, see :doc:`integrating_into_django`.
-1. Install Wagtail and its dependencies::
+1. Install Wagtail and its dependencies:
- pip install wagtail
+ .. code-block:: console
-2. Start your site::
+ $ pip install wagtail
- wagtail start mysite
- cd mysite
+2. Start your site:
+
+ .. code-block:: console
+
+ $ wagtail start mysite
+ $ cd mysite
Wagtail provides a ``start`` command similar to
``django-admin.py startproject``. Running ``wagtail start mysite`` in
@@ -20,22 +24,28 @@ Your first Wagtail site
"home" app with a blank ``HomePage`` model and basic templates and a sample
"search" app.
-3. Install project dependencies::
+3. Install project dependencies:
- pip install -r requirements.txt
+ .. code-block:: console
+
+ $ pip install -r requirements.txt
This ensures that you have the relevant version of Django for the project you've just created.
-4. Create the database::
+4. Create the database:
- python manage.py migrate
+ .. code-block:: console
+
+ $ python manage.py migrate
If you haven't updated the project settings, this will be a SQLite
database file in the project directory.
-5. Create an admin user::
+5. Create an admin user:
- python manage.py createsuperuser
+ .. code-block:: console
+
+ $ python manage.py createsuperuser
6. ``python manage.py runserver`` If everything worked,
http://127.0.0.1:8000 will show you a welcome page
diff --git a/docs/reference/contrib/staticsitegen.rst b/docs/reference/contrib/staticsitegen.rst
index eea1f4538..d764f85b1 100644
--- a/docs/reference/contrib/staticsitegen.rst
+++ b/docs/reference/contrib/staticsitegen.rst
@@ -12,9 +12,9 @@ Installing ``django-medusa``
First, install ``django-medusa`` and ``django-sendfile`` from pip:
-.. code-block:: sh
+.. code-block:: console
- pip install django-medusa django-sendfile
+ $ pip install django-medusa django-sendfile
Then add ``django_medusa`` and ``wagtail.contrib.wagtailmedusa`` to ``INSTALLED_APPS``:
diff --git a/docs/reference/management_commands.rst b/docs/reference/management_commands.rst
index 49aaa4238..10b539933 100644
--- a/docs/reference/management_commands.rst
+++ b/docs/reference/management_commands.rst
@@ -9,7 +9,9 @@ Management commands
publish_scheduled_pages
-----------------------
-:code:`./manage.py publish_scheduled_pages`
+.. code-block:: console
+
+ $ ./manage.py publish_scheduled_pages
This command publishes or unpublishes pages that have had these actions scheduled by an editor. It is recommended to run this command once an hour.
@@ -19,7 +21,9 @@ This command publishes or unpublishes pages that have had these actions schedule
fixtree
-------
-:code:`./manage.py fixtree`
+.. code-block:: console
+
+ $ ./manage.py fixtree
This command scans for errors in your database and attempts to fix any issues it finds.
@@ -29,7 +33,9 @@ This command scans for errors in your database and attempts to fix any issues it
move_pages
----------
-:code:`manage.py move_pages from to`
+.. code-block:: console
+
+ $ manage.py move_pages from to
This command moves a selection of pages from one section of the tree to another.
@@ -47,7 +53,9 @@ Options:
update_index
------------
-:code:`./manage.py update_index [--backend ]`
+.. code-block:: console
+
+ $ ./manage.py update_index [--backend ]
This command rebuilds the search index from scratch. It is only required when using Elasticsearch.
@@ -71,9 +79,9 @@ If you have multiple backends and would only like to update one of them, you can
For example, to update just the default backend:
-.. code-block:: sh
+.. code-block:: console
- python manage.py update_index --backend default
+ $ python manage.py update_index --backend default
Indexing the schema only
@@ -83,9 +91,9 @@ Indexing the schema only
You can prevent the ``update_index`` command from indexing any data by using the ``--schema-only`` option:
-.. code-block:: sh
+.. code-block:: console
- python manage.py update_index --schema-only
+ $ python manage.py update_index --schema-only
.. _search_garbage_collect:
@@ -93,6 +101,8 @@ You can prevent the ``update_index`` command from indexing any data by using the
search_garbage_collect
----------------------
-:code:`./manage.py search_garbage_collect`
+.. code-block:: console
+
+ $ ./manage.py search_garbage_collect
Wagtail keeps a log of search queries that are popular on your website. On high traffic websites, this log may get big and you may want to clean out old search queries. This command cleans out all search query logs that are more than one week old (or a number of days configurable through the :ref:`WAGTAILSEARCH_HITS_MAX_AGE ` setting).
diff --git a/docs/releases/0.5.rst b/docs/releases/0.5.rst
index 6f4912de5..1ae29f428 100644
--- a/docs/releases/0.5.rst
+++ b/docs/releases/0.5.rst
@@ -117,9 +117,11 @@ Since Wagtail 0.3, the wagtailadmin module automatically takes care of registeri
New fields on Image and Rendition models
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Several new fields have been added to the Image and Rendition models to support :ref:`image_feature_detection`. These will be added to the database when you run ``./manage.py migrate``. If you have defined a custom image model (by extending the ``wagtailimages.AbstractImage`` and ``wagtailimages.AbstractRendition`` classes and specifying ``WAGTAILIMAGES_IMAGE_MODEL`` in settings), the change needs to be applied to that model's database table too. Running the command::
+Several new fields have been added to the Image and Rendition models to support :ref:`image_feature_detection`. These will be added to the database when you run ``./manage.py migrate``. If you have defined a custom image model (by extending the ``wagtailimages.AbstractImage`` and ``wagtailimages.AbstractRendition`` classes and specifying ``WAGTAILIMAGES_IMAGE_MODEL`` in settings), the change needs to be applied to that model's database table too. Running the command:
- ./manage.py schemamigration myapp --auto add_image_focal_point_fields
+.. code-block:: console
+
+ $ ./manage.py schemamigration myapp --auto add_image_focal_point_fields
(with 'myapp' replaced with your app name) will generate the necessary migration file.
diff --git a/docs/releases/0.8.6.rst b/docs/releases/0.8.6.rst
index 1a177d955..f6371c55a 100644
--- a/docs/releases/0.8.6.rst
+++ b/docs/releases/0.8.6.rst
@@ -30,9 +30,11 @@ Upgrade considerations
Orphaned pages may need deleting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This release fixes a bug with page deletion introduced in 0.8, where deleting a page with child pages will result in those child pages being left behind in the database (unless the child pages are of the same type as the parent). This may cause errors later on when creating new pages in the same position. To identify and delete these orphaned pages, it is recommended that you run the following command (from the project root) after upgrading to 0.8.6::
+This release fixes a bug with page deletion introduced in 0.8, where deleting a page with child pages will result in those child pages being left behind in the database (unless the child pages are of the same type as the parent). This may cause errors later on when creating new pages in the same position. To identify and delete these orphaned pages, it is recommended that you run the following command (from the project root) after upgrading to 0.8.6:
- ./manage.py fixtree
+.. code-block:: console
+
+ $ ./manage.py fixtree
This will output a list of any orphaned pages found, and request confirmation before deleting them.
diff --git a/docs/topics/search/backends.rst b/docs/topics/search/backends.rst
index 6971545f9..72ae988e6 100644
--- a/docs/topics/search/backends.rst
+++ b/docs/topics/search/backends.rst
@@ -90,13 +90,13 @@ Prerequisites are the `Elasticsearch`_ service itself and, via pip, the `elastic
.. _Elasticsearch: https://www.elastic.co/downloads/past-releases/elasticsearch-1-7-3
-.. code-block:: sh
+.. code-block:: console
- pip install "elasticsearch>=1.0.0,<2.0.0" # for Elasticsearch 1.x
+ $ pip install "elasticsearch>=1.0.0,<2.0.0" # for Elasticsearch 1.x
-.. code-block:: sh
+.. code-block:: console
- pip install "elasticsearch>=2.0.0,<3.0.0" # for Elasticsearch 2.x
+ $ pip install "elasticsearch>=2.0.0,<3.0.0" # for Elasticsearch 2.x
The backend is configured in settings: