From bf6607de54a4ac8f4bdb2e45f5fb240a5d47eaef Mon Sep 17 00:00:00 2001 From: Dave Cranwell Date: Thu, 14 May 2015 14:02:06 +0100 Subject: [PATCH 1/6] moved styleguide to own page. renamed trying wagtail to demo site --- docs/contributing/index.rst | 1 + docs/contributing/styleguide.rst | 18 ++++++++++++++++++ .../{trying_wagtail.rst => demo_site.rst} | 0 docs/getting_started/index.rst | 2 +- docs/index.rst | 2 +- 5 files changed, 21 insertions(+), 2 deletions(-) create mode 100644 docs/contributing/styleguide.rst rename docs/getting_started/{trying_wagtail.rst => demo_site.rst} (100%) diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst index 36947041b..519eae512 100644 --- a/docs/contributing/index.rst +++ b/docs/contributing/index.rst @@ -6,5 +6,6 @@ Contributing to Wagtail :maxdepth: 2 developing + styleguide css_guidelines javascript_guidelines diff --git a/docs/contributing/styleguide.rst b/docs/contributing/styleguide.rst new file mode 100644 index 000000000..fd5231fdc --- /dev/null +++ b/docs/contributing/styleguide.rst @@ -0,0 +1,18 @@ +Styleguide +========== + +Developers working on the Wagtail UI or creating new UI components may wish to test their work against our Styleguide, which is provided as the contrib module "wagtailstyleguide". + +To install the styleguide module on your site, add it to the list of ``INSTALLED_APPS`` in your settings: + +.. code-block:: python + + INSTALLED_APPS = ( + ... + 'wagtail.contrib.wagtailstyleguide', + ... + ) + +At present the styleguide is static: new UI components must be added to it manually, and there are no hooks into it for other modules to use. We hope to support hooks in the future. + +The styleguide doesn't currently provide examples of all the core interface components; notably the Page, Document, Image and Snippet chooser interfaces are not currently represented. \ No newline at end of file diff --git a/docs/getting_started/trying_wagtail.rst b/docs/getting_started/demo_site.rst similarity index 100% rename from docs/getting_started/trying_wagtail.rst rename to docs/getting_started/demo_site.rst diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst index 8b72c0206..e308574f7 100644 --- a/docs/getting_started/index.rst +++ b/docs/getting_started/index.rst @@ -5,7 +5,7 @@ Getting started .. toctree:: :maxdepth: 2 - trying_wagtail installation creating_your_project using_vagrant + demo_site diff --git a/docs/index.rst b/docs/index.rst index 5a6626428..ae6e4d63a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,7 +8,7 @@ Below are some useful links to help you get started with Wagtail. * **First steps** - * :doc:`getting_started/trying_wagtail` + * :doc:`getting_started/demo_site` * :doc:`getting_started/installation` * :doc:`getting_started/creating_your_project` From ef4d9b00c5c864e255f3905ee1b5f84005d28666 Mon Sep 17 00:00:00 2001 From: Dave Cranwell Date: Thu, 14 May 2015 14:03:11 +0100 Subject: [PATCH 2/6] moved github issues/pr info into index page, leaving the developing page more about actual development, not housekeeping --- docs/contributing/developing.rst | 64 +++++++++++++------------------- docs/contributing/index.rst | 25 +++++++++++++ 2 files changed, 50 insertions(+), 39 deletions(-) diff --git a/docs/contributing/developing.rst b/docs/contributing/developing.rst index 3297268b7..c70608ccf 100644 --- a/docs/contributing/developing.rst +++ b/docs/contributing/developing.rst @@ -1,15 +1,32 @@ -Developing Wagtail +Development environment ----------------------- -Issues -~~~~~~ +Using the demo site & Vagrant +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The easiest way to contribute to Wagtail is to tell us how to improve it! First, check to see if your bug or feature request has already been submitted at `github.com/torchbox/wagtail/issues `_. If it has, and you have some supporting information which may help us deal with it, comment on the existing issue. If not, please `create a new one `_, providing as much relevant context as possible. For example, if you're experiencing problems with installation, detail your environment and the steps you've already taken. If something isn't displaying correctly, tell us what browser you're using, and include a screenshot if possible. +We recommend using the `Wagtail demo site `_ which uses Vagrant, as a basis for developing Wagtail itself. -Pull requests -~~~~~~~~~~~~~ +Install the wagtaildemo following the instructions in the `wagtaildemo README `_, then continue with the instructions below. + +Clone a copy of `the Wagtail codebase `_ alongside your demo site at the same level. So in the directory containing wagtaildemo, run:: + + git clone https://github.com/torchbox/wagtail.git + +Enable the Vagrantfile included with the demo - this ensures you can edit the Wagtail codebase from outside Vagrant:: + + cd wagtaildemo + cp Vagrantfile.local.example Vagrantfile.local + +If you clone Wagtail's codebase to somewhere other than one level above, edit ``Vagrantfile.local`` to specify the alternate path. + +Lastly, we tell Django to use your freshly cloned Wagtail codebase as the source of Wagtail CMS, not the pip-installed version that came with wagtaildemo:: + + cp wagtaildemo/settings/local.py.example wagtaildemo/settings/local.py + +Uncomment the lines from ``import sys`` onward, and edit the rest of ``local.py`` as appropriate. + +If your VM is currently running, you'll then need to run ``vagrant halt`` followed by ``vagrant up`` for the changes to take effect. -If you're a Python or Django developer, `fork `_ and get stuck in! Send us a useful pull request and we'll post you a `t-shirt `_. We welcome all contributions, whether they solve problems which are specific to you or they address existing issues. If you're stuck for ideas, pick something from the `issue list `_, or email us directly on `hello@wagtail.io `_ if you'd like us to suggest something! Coding guidelines ~~~~~~~~~~~~~~~~~ @@ -18,6 +35,7 @@ Coding guidelines * Python 2 and 3 compatibility. All contributions should support Python 2 and 3 and we recommend using the `six `_ compatibility library (use the pip version installed as a dependency, not the version bundled with Django). * Tests. Wagtail has a suite of tests, which we are committed to improving and expanding. We run continuous integration at `travis-ci.org/torchbox/wagtail `_ to ensure that no commits or pull requests introduce test failures. If your contributions add functionality to Wagtail, please include the additional tests to cover it; if your contributions alter existing functionality, please update the relevant tests accordingly. + Running the unit tests ~~~~~~~~~~~~~~~~~~~~~~ @@ -81,35 +99,3 @@ If your Elasticsearch instance is located somewhere else, you can set the If you no longer want Wagtail to test against Elasticsearch, uninstall the ``elasticsearch`` package. - -Styleguide -~~~~~~~~~~ - -Developers working on the Wagtail UI or creating new UI components may wish to test their work against our Styleguide, which is provided as the contrib module "wagtailstyleguide". - -To install the styleguide module on your site, add it to the list of ``INSTALLED_APPS`` in your settings: - -.. code-block:: python - - INSTALLED_APPS = ( - ... - 'wagtail.contrib.wagtailstyleguide', - ... - ) - -At present the styleguide is static: new UI components must be added to it manually, and there are no hooks into it for other modules to use. We hope to support hooks in the future. - -The styleguide doesn't currently provide examples of all the core interface components; notably the Page, Document, Image and Snippet chooser interfaces are not currently represented. - - -Translations -~~~~~~~~~~~~ - -Wagtail has internationalisation support so if you are fluent in a non-English language you can contribute by localising the interface. - -Translation work should be submitted through `Transifex `_. - -Other contributions -~~~~~~~~~~~~~~~~~~~ - -We welcome contributions to all aspects of Wagtail. If you would like to improve the design of the user interface, or extend the documentation, please submit a pull request as above. If you're not familiar with Github or pull requests, `contact us directly `_ and we'll work something out. diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst index 519eae512..ed64f9710 100644 --- a/docs/contributing/index.rst +++ b/docs/contributing/index.rst @@ -1,6 +1,31 @@ Contributing to Wagtail ======================= +Issues +~~~~~~ + +The easiest way to contribute to Wagtail is to tell us how to improve it! First, check to see if your bug or feature request has already been submitted at `github.com/torchbox/wagtail/issues `_. If it has, and you have some supporting information which may help us deal with it, comment on the existing issue. If not, please `create a new one `_, providing as much relevant context as possible. For example, if you're experiencing problems with installation, detail your environment and the steps you've already taken. If something isn't displaying correctly, tell us what browser you're using, and include a screenshot if possible. + +Pull requests +~~~~~~~~~~~~~ + +If you're a Python or Django developer, `fork `_ and get stuck in! Send us a useful pull request and we'll post you a `t-shirt `_. We welcome all contributions, whether they solve problems which are specific to you or they address existing issues. If you're stuck for ideas, pick something from the `issue list `_, or email us directly on `hello@wagtail.io `_ if you'd like us to suggest something! + + +Translations +~~~~~~~~~~~~ + +Wagtail has internationalisation support so if you are fluent in a non-English language you can contribute by localising the interface. + +Translation work should be submitted through `Transifex `_. + + +Other contributions +~~~~~~~~~~~~~~~~~~~ + +We welcome contributions to all aspects of Wagtail. If you would like to improve the design of the user interface, or extend the documentation, please submit a pull request as above. If you're not familiar with Github or pull requests, `contact us directly `_ and we'll work something out. + + .. toctree:: :maxdepth: 2 From 66a901c48c18b47899c1ce132f0d17ca00283067 Mon Sep 17 00:00:00 2001 From: Dave Cranwell Date: Thu, 14 May 2015 14:04:30 +0100 Subject: [PATCH 3/6] removed duplicated/out-of-date information about getting started using the demo site. this is now only in the actual wagtaildemo repo --- docs/contributing/developing.rst | 19 ++---- docs/contributing/index.rst | 1 + docs/contributing/python_guidelines.rst | 6 ++ docs/getting_started/demo_site.rst | 80 ++----------------------- 4 files changed, 17 insertions(+), 89 deletions(-) create mode 100644 docs/contributing/python_guidelines.rst diff --git a/docs/contributing/developing.rst b/docs/contributing/developing.rst index c70608ccf..fdef61cf7 100644 --- a/docs/contributing/developing.rst +++ b/docs/contributing/developing.rst @@ -1,5 +1,5 @@ -Development environment ------------------------ +Development process +------------------- Using the demo site & Vagrant ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -28,19 +28,10 @@ Uncomment the lines from ``import sys`` onward, and edit the rest of ``local.py` If your VM is currently running, you'll then need to run ``vagrant halt`` followed by ``vagrant up`` for the changes to take effect. -Coding guidelines -~~~~~~~~~~~~~~~~~ - -* PEP8. We ask that all Python contributions adhere to the `PEP8 `_ style guide, apart from the restriction on line length (E501). The `pep8 tool `_ makes it easy to check your code, e.g. ``pep8 --ignore=E501 your_file.py``. -* Python 2 and 3 compatibility. All contributions should support Python 2 and 3 and we recommend using the `six `_ compatibility library (use the pip version installed as a dependency, not the version bundled with Django). -* Tests. Wagtail has a suite of tests, which we are committed to improving and expanding. We run continuous integration at `travis-ci.org/torchbox/wagtail `_ to ensure that no commits or pull requests introduce test failures. If your contributions add functionality to Wagtail, please include the additional tests to cover it; if your contributions alter existing functionality, please update the relevant tests accordingly. - - -Running the unit tests -~~~~~~~~~~~~~~~~~~~~~~ - -In order to run Wagtail's test suite, you will need to install some dependencies first. We recommend installing these into a virtual environment. +Unit tests +~~~~~~~~~~ +Wagtail has extensive tests which should be run before submitting pull requests. To run Wagtail's test suite you will need to install some dependencies. We recommend installing these into a virtual environment. **Setting up the virtual environment** diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst index ed64f9710..76b0b61f9 100644 --- a/docs/contributing/index.rst +++ b/docs/contributing/index.rst @@ -32,5 +32,6 @@ We welcome contributions to all aspects of Wagtail. If you would like to improve developing styleguide + python_guidelines css_guidelines javascript_guidelines diff --git a/docs/contributing/python_guidelines.rst b/docs/contributing/python_guidelines.rst new file mode 100644 index 000000000..a20cd4de7 --- /dev/null +++ b/docs/contributing/python_guidelines.rst @@ -0,0 +1,6 @@ +Python coding guidelines +======================== + +* PEP8. We ask that all Python contributions adhere to the `PEP8 `_ style guide, apart from the restriction on line length (E501). The `pep8 tool `_ makes it easy to check your code, e.g. ``pep8 --ignore=E501 your_file.py``. +* Python 2 and 3 compatibility. All contributions should support Python 2 and 3 and we recommend using the `six `_ compatibility library (use the pip version installed as a dependency, not the version bundled with Django). +* Tests. Wagtail has a suite of tests, which we are committed to improving and expanding. We run continuous integration at `travis-ci.org/torchbox/wagtail `_ to ensure that no commits or pull requests introduce test failures. If your contributions add functionality to Wagtail, please include the additional tests to cover it; if your contributions alter existing functionality, please update the relevant tests accordingly. diff --git a/docs/getting_started/demo_site.rst b/docs/getting_started/demo_site.rst index e08793308..a3116c8f4 100644 --- a/docs/getting_started/demo_site.rst +++ b/docs/getting_started/demo_site.rst @@ -1,78 +1,8 @@ -============== -Trying Wagtail -============== +========= +Demo site +========= -Wagtail demo -============ +To create a new site on Wagtail we recommend the ``wagtail start`` command in :doc:`creating_your_project`, however a demo site exists containing example page types and models. The demo site is also our recommended basis for contributing to Wagtail itself. -We provide a demo site containing a set of standard templates and page types - if you're new to Wagtail, this is the best way to try it out and familiarise yourself with how Wagtail works from the point of view of an editor. - -If you're happy to use Vagrant, and you just want to set up the Wagtail demo site, or any other pre-existing Wagtail site that ships with Vagrant support, you don't need to install Wagtail at all. Install `Vagrant `__ and `VirtualBox `__, and run:: - - git clone https://github.com/torchbox/wagtaildemo.git - cd wagtaildemo - vagrant up - vagrant ssh - - -Then, within the SSH session:: - - ./manage.py createsuperuser - ./manage.py runserver 0.0.0.0:8000 - - -This will make the demo site available on your host machine at the URL http://localhost:8000/ - you can access the Wagtail admin interface at http://localhost:8000/admin/ . Further instructions can be found at :ref:`editor_manual`. - -Once you’ve experimented with the demo site and are ready to build your own site, it's time to install Wagtail on your host machine. Even if you intend to do all further Wagtail work within Vagrant, installing the Wagtail package on your host machine will provide the ``wagtail start`` command that sets up the initial file structure for your project. - - -One line install -================ - - -Ubuntu ------- - -If you have a fresh instance of Ubuntu 13.04 or later, you can install Wagtail, -along with a demonstration site containing a set of standard templates and page -types, in one step. As the root user:: - - curl -O https://raw.githubusercontent.com/torchbox/wagtail/master/scripts/install/ubuntu.sh; bash ubuntu.sh - -This script installs all the dependencies for a production-ready Wagtail site, -including PostgreSQL, Redis, Elasticsearch, Nginx and uWSGI. We -recommend you check through the script before running it, and adapt it according -to your deployment preferences. The canonical version is at -`github.com/torchbox/wagtail/blob/master/scripts/install/ubuntu.sh -`_. - - -Debian ------- - -If you have a fresh instance of Debian 7, you can install Wagtail, along with a -demonstration site containing a set of standard templates and page types, in one -step. As the root user:: - - curl -O https://raw.githubusercontent.com/torchbox/wagtail/master/scripts/install/debian.sh; bash debian.sh - -This script installs all the dependencies for a production-ready Wagtail site, -including PostgreSQL, Redis, Elasticsearch, Nginx and uWSGI. We -recommend you check through the script before running it, and adapt it according -to your deployment preferences. The canonical version is at -`github.com/torchbox/wagtail/blob/master/scripts/install/debian.sh -`_. - - -Docker -====== - -`@oyvindsk `_ has built a Dockerfile for the Wagtail demo. Simply run:: - - docker run -p 8000:8000 -d oyvindsk/wagtail-demo - -then access the site at http://your-ip:8000 and the admin -interface at http://your-ip:8000/admin using admin / test. - -See https://index.docker.io/u/oyvindsk/wagtail-demo/ for more details. +The repo and installation instructions can be found here: `https://github.com/torchbox/wagtaildemo `_ From 2ab94a002218550c918d8eb7ec5af7d18a7b7bc8 Mon Sep 17 00:00:00 2001 From: Dave Cranwell Date: Thu, 14 May 2015 14:21:36 +0100 Subject: [PATCH 4/6] made difference clearer between coding style and styleguide --- docs/contributing/developing.rst | 25 +++++++++++++++++-------- docs/contributing/styleguide.rst | 4 ++-- 2 files changed, 19 insertions(+), 10 deletions(-) diff --git a/docs/contributing/developing.rst b/docs/contributing/developing.rst index fdef61cf7..290ae4731 100644 --- a/docs/contributing/developing.rst +++ b/docs/contributing/developing.rst @@ -1,5 +1,5 @@ -Development process -------------------- +Development +----------- Using the demo site & Vagrant ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -28,12 +28,22 @@ Uncomment the lines from ``import sys`` onward, and edit the rest of ``local.py` If your VM is currently running, you'll then need to run ``vagrant halt`` followed by ``vagrant up`` for the changes to take effect. -Unit tests -~~~~~~~~~~ +Development dependencies +~~~~~~~~~~~~~~~~~~~~~~~~ -Wagtail has extensive tests which should be run before submitting pull requests. To run Wagtail's test suite you will need to install some dependencies. We recommend installing these into a virtual environment. +Developing Wagtail requires additional Python modules for testing and documentation. -**Setting up the virtual environment** +The list of dependencies is in the Wagtail root directory in ``requirements-dev.txt`` and if you've used the Vagrant environment above, can be installed thus, from the Wagtail codebase root directory:: + + pip install -r requirements-dev.txt + + +Testing +~~~~~~~ + +Wagtail has unit tests which should be run before submitting pull requests. + +**Testing virtual environment** (skip this if working in Vagrant box) If you are using Python 3.3 or above, run the following commands in your shell at the root of the Wagtail repo:: @@ -50,8 +60,7 @@ the first line above with: **Running the tests** -With your virtual environment active, 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 diff --git a/docs/contributing/styleguide.rst b/docs/contributing/styleguide.rst index fd5231fdc..a2357e5fc 100644 --- a/docs/contributing/styleguide.rst +++ b/docs/contributing/styleguide.rst @@ -1,5 +1,5 @@ -Styleguide -========== +UI Styleguide +============= Developers working on the Wagtail UI or creating new UI components may wish to test their work against our Styleguide, which is provided as the contrib module "wagtailstyleguide". From d507ce9ea1860570e83b6d06915045b6dff63e1e Mon Sep 17 00:00:00 2001 From: Dave Cranwell Date: Fri, 15 May 2015 09:25:06 +0100 Subject: [PATCH 5/6] wording change --- docs/getting_started/demo_site.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting_started/demo_site.rst b/docs/getting_started/demo_site.rst index a3116c8f4..658115417 100644 --- a/docs/getting_started/demo_site.rst +++ b/docs/getting_started/demo_site.rst @@ -3,6 +3,6 @@ Demo site ========= -To create a new site on Wagtail we recommend the ``wagtail start`` command in :doc:`creating_your_project`, however a demo site exists containing example page types and models. The demo site is also our recommended basis for contributing to Wagtail itself. +To create a new site on Wagtail we recommend the ``wagtail start`` command in :doc:`creating_your_project`, however a demo site exists containing example page types and models. We also recommend you use the demo site for testing during development of Wagtail itself. The repo and installation instructions can be found here: `https://github.com/torchbox/wagtaildemo `_ From 5a1f4de23cee2a7daa536b902526e9346b95619a Mon Sep 17 00:00:00 2001 From: Dave Cranwell Date: Fri, 15 May 2015 09:33:45 +0100 Subject: [PATCH 6/6] replaced bullets with headings in python guidelines --- docs/contributing/developing.rst | 2 ++ docs/contributing/python_guidelines.rst | 21 ++++++++++++++++++--- 2 files changed, 20 insertions(+), 3 deletions(-) diff --git a/docs/contributing/developing.rst b/docs/contributing/developing.rst index 290ae4731..77b715f68 100644 --- a/docs/contributing/developing.rst +++ b/docs/contributing/developing.rst @@ -38,6 +38,8 @@ The list of dependencies is in the Wagtail root directory in ``requirements-dev. pip install -r requirements-dev.txt +.. _testing: + Testing ~~~~~~~ diff --git a/docs/contributing/python_guidelines.rst b/docs/contributing/python_guidelines.rst index a20cd4de7..0956c264b 100644 --- a/docs/contributing/python_guidelines.rst +++ b/docs/contributing/python_guidelines.rst @@ -1,6 +1,21 @@ Python coding guidelines ======================== -* PEP8. We ask that all Python contributions adhere to the `PEP8 `_ style guide, apart from the restriction on line length (E501). The `pep8 tool `_ makes it easy to check your code, e.g. ``pep8 --ignore=E501 your_file.py``. -* Python 2 and 3 compatibility. All contributions should support Python 2 and 3 and we recommend using the `six `_ compatibility library (use the pip version installed as a dependency, not the version bundled with Django). -* Tests. Wagtail has a suite of tests, which we are committed to improving and expanding. We run continuous integration at `travis-ci.org/torchbox/wagtail `_ to ensure that no commits or pull requests introduce test failures. If your contributions add functionality to Wagtail, please include the additional tests to cover it; if your contributions alter existing functionality, please update the relevant tests accordingly. +PEP8 +~~~~ + +We ask that all Python contributions adhere to the `PEP8 `_ style guide, apart from the restriction on line length (E501). The `pep8 tool `_ makes it easy to check your code, e.g. ``pep8 --ignore=E501 your_file.py``. + + +Python 2 and 3 compatibility +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All contributions should support Python 2 and 3 and we recommend using the `six `_ compatibility library (use the pip version installed as a dependency, not the version bundled with Django). + + +Tests +~~~~~ + +Wagtail has a suite of tests, which we are committed to improving and expanding. See :ref:`testing`. + +We run continuous integration at `travis-ci.org/torchbox/wagtail `_ to ensure that no commits or pull requests introduce test failures. If your contributions add functionality to Wagtail, please include the additional tests to cover it; if your contributions alter existing functionality, please update the relevant tests accordingly.