Hopiu/wagtail
1
0
Fork 0
mirror of https://github.com/Hopiu/wagtail.git synced 2026-03-16 22:10:28 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Use .. code-block:: console for all shell commands

Browse source 
This is the correct lexer for interactive console sessions, according to
<http://pygments.org/docs/lexers/>. This does require command lines to
be prefixed with `$`, otherwise they are interpreted as the output of a
command. It highlights the command nicely, including environment
variables, strings, and comments.
This commit is contained in:
Tim Heap 2016-11-28 12:30:44 +11:00 committed by Matt Westcott
parent f742d4a476
commit 254e675634
14 changed files with 156 additions and 103 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
docs/advanced_topics/images/feature_detection.rst
View file

@ -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.

12
docs/advanced_topics/performance.rst
View file

@ -33,7 +33,11 @@ Search
Wagtail has strong support for `Elasticsearch <http://www.elasticsearch.org/>`_ - 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 <http://www.searchly.com/>`_.
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

4
docs/advanced_topics/settings.rst
View file

@ -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

22
docs/contributing/committing.rst
View file

@ -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

10
docs/contributing/css_guidelines.rst
View file

@ -12,14 +12,14 @@ This requires `node.js <http://nodejs.org>`_ 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

84
docs/contributing/developing.rst
View file

@ -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 <https://github.com/torchbox/wagtail>`_:
.. 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 <https://github.com/torchbox/wagtaildemo/>`_ 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 <http://localhost:8080/> 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

15
docs/contributing/javascript_guidelines.rst
View file

@ -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 <http://jscs.info/>`_ library.

24
docs/getting_started/index.rst
View file

@ -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 <http://pillow.readthedocs.org/en/latest/installation.html#external-libraries>`_.
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 </reference/project_template>`.
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/``.

32
docs/getting_started/tutorial.rst
View file

@ -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

4
docs/reference/contrib/staticsitegen.rst
View file

@ -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``:

28
docs/reference/management_commands.rst
View file

@ -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 <backend name>]`
.. code-block:: console
$ ./manage.py update_index [--backend <backend name>]
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 <wagtailsearch_hits_max_age>` setting).

6
docs/releases/0.5.rst
View file

@ -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.

6
docs/releases/0.8.6.rst
View file

@ -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.

8
docs/topics/search/backends.rst
View file

@ -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: