diff mbox

[03/11] docs: Rewrite documentation

Message ID 1435585571-25252-4-git-send-email-stephen.finucane@intel.com
State Superseded
Headers show

Commit Message

Stephen Finucane June 29, 2015, 1:46 p.m. UTC
From: Stephen Finucane <stephenfinucane@hotmail.com>

The INSTALL and HACKING documents are an important guide for new
patchwork users and developers and should be as informative as
possible. A number of changes were needed to these documents owing
to the out-of-date or incomplete information they contained. These
changes include:

* Removing references to the dead mod_python/flup projects
* Adding references to Gunicorn+nginx, which a credible modern
  alternative to Apache+mod_wsgi
* Providing explanatory links to concepts/tools like ident-based
  authentication and tox
* Referencing the newer tools available to developers, like tox
  and the 'requirements.txt' files
* Integration with mkdocs, with eye on eventual publishing of
  documentation to ReadTheDocs or equivalent.

These changes result in a significant rewrite which should hopefully
lower the barrier to entry for people wishing to use or develop
patchwork.

Signed-off-by: Stephen Finucane <stephen.finucane@intel.com>
---
 docs/HACKING                             |  69 -------
 docs/INSTALL                             | 305 -------------------------------
 docs/development.md                      |  95 ++++++++++
 docs/index.md                            |  66 +++++++
 docs/installation.md                     | 290 +++++++++++++++++++++++++++++
 mkdocs.yml                               |  10 +
 patchwork/settings/production.example.py |   2 +-
 7 files changed, 462 insertions(+), 375 deletions(-)
 delete mode 100644 docs/HACKING
 delete mode 100644 docs/INSTALL
 create mode 100644 docs/development.md
 create mode 100644 docs/index.md
 create mode 100644 docs/installation.md
 create mode 100644 mkdocs.yml
diff mbox

Patch

diff --git a/docs/HACKING b/docs/HACKING
deleted file mode 100644
index c1b478e..0000000
--- a/docs/HACKING
+++ /dev/null
@@ -1,69 +0,0 @@ 
-== Using virtualenv
-
-It's always a good idea to use virtualenv to develop python software.
-
-1. Install pip, virtualenv (python-pip, python-virtualenv packages)
-
-   Because we're going to recompile our dependencies, we'll also need
-   development headers:
-
-   - For the MySQL/MariaDB setups: mariadb-devel (Fedora), libmysqlclient-dev
-     (Debian)
-
-2. Create a new virtual environement. Virtual environments are "instances" of
-   your system python, without any of the extra python packages installed.
-   Inside a virtual env, we'll just install the dependencies needed for
-   patchwork and run it from there.
-
-   Virtual envs are useful to develop and deploy patchwork against a "well
-   known" set of dependencies. They can also be used to test patchwork against
-   several versions of django, creating a separate virtual env per version.
-
-   $ virtualenv django-1.7
-
-   will create a virtual env called 'django-1.7' in eponymous directory.
-
-3. Activate a virtual environment
-
-   $ sources django-1.7/bin/activate
-   (django-1.7)$
-
-   The shell prompt is preprended with the virtual env name.
-
-4. Install the required dependencies
-
-   To ease this task, it's customary to maintain a list of dependencies in a
-   text file and install them in one go. One can maintain such a list of
-   dependencies per interesting configuration.
-
-   (django-1.7)$ pip install -r docs/requirements-django-1.7-mysql.txt
-
-   Of course, this is a one-time step, once installed in the virtual
-   environment, no need to to install the requirements everytime.
-
-5. Now one can run patchwork within that environment
-
-   (django-1.7)$ ./manage.py --version
-   1.7
-   (django-1.7)$ ./manage.py runserver
-
-6. To exit the virtual environment
-
-   (django-1.7)$ deactivate
-   $
-
-
-== Running tests
-
-- To run all tests:
-
-  $ ./manage.py test
-
-- To run all test methods (methods which name starts with 'test') of a TestCase
-  subclass:
-
-  $ ./manage.py test patchwork.tests.SubjectCleanUpTest
-
-- To run a single test:
-
-  $ ./manage.py test patchwork.tests.SubjectCleanUpTest.testSubjectCleanup
diff --git a/docs/INSTALL b/docs/INSTALL
deleted file mode 100644
index bd95770..0000000
--- a/docs/INSTALL
+++ /dev/null
@@ -1,305 +0,0 @@ 
-Deploying Patchwork
-
-Patchwork uses the django framework - there is some background on deploying
-django applications here:
-
- http://www.djangobook.com/en/2.0/chapter12/
-
-You'll need the following (applications used for patchwork development are
-in brackets):
-
-  * A python interpreter
-  * django >= 1.5
-  * A webserver (apache)
-  * mod_python or flup
-  * A database server (postgresql, mysql)
-  * relevant python modules for the database server (e.g: python-mysqldb)
-
-
-1. Database setup
-
-    At present, I've tested with PostgreSQL and (to a lesser extent) MySQL
-    database servers. If you have any (positive or negative) experiences with
-    either, email me.
-
-    For the following commands, a $ prefix signifies that the command should be
-    entered at your shell prompt, and a > prefix signifies the command-line
-    client for your sql server (psql or mysql)
-
-    Create a database for the system, add accounts for two system users: the
-    web user (the user that your web server runs as) and the mail user (the
-    user that your mail server runs as). On Ubuntu these are
-    www-data and nobody, respectively.
-
-    As an alternative, you can use password-based login and a single database
-    account. This is described further down.
-
-    For PostgreSQL (ident-based)
-
-        $ createdb patchwork
-        $ createuser www-data
-        $ createuser nobody
-
-        - postgres uses the standard UNIX authentication, so these users
-          will only be accessible for processes running as the same username.
-          This means that no passwords need to be set.
-
-    For PostgreSQL (password-based)
-
-        $ createuser -PE patchwork
-        $ createdb -O patchwork patchwork
-
-        Once that is done, you need to tell Django about the new Database
-        settings, using local_settings.py (see below) to override the defaults
-        in settings.py:
-
-        DATABASES = {
-            'default': {
-                'ENGINE': 'django.db.backends.postgresql_psycopg2',
-                'HOST': 'localhost',
-                'PORT': '',
-                'USER': 'patchwork',
-                'PASSWORD': 'my_secret_password',
-                'NAME': 'patchwork',
-            },
-        }
-
-    For MySQL:
-        $ mysql
-        > CREATE DATABASE patchwork CHARACTER SET utf8;
-        > CREATE USER 'www-data'@'localhost' IDENTIFIED BY '<password>';
-        > CREATE USER 'nobody'@'localhost' IDENTIFIED BY '<password>';
-
-	Once that is done, you need to tell Django about the new Database
-	settings, using local_settings.py (see below) to override the defaults
-	in settings.py:
-
-        DATABASES = {
-            'default': {
-                'ENGINE': 'django.db.backends.mysql',
-                'HOST': 'localhost',
-                'PORT': '',
-                'USER': 'patchwork',
-                'PASSWORD': 'my_secret_password',
-                'NAME': 'patchwork',
-                'TEST_CHARSET': 'utf8',
-            },
-        }
-
-        TEST_CHARSET is used when creating tables for the test suite. Without
-        it, tests checking for the correct handling of non-ASCII characters
-        fail.
-
-
-2. Django setup
-
-    Set up some initial directories in the patchwork base directory:
-
-      mkdir -p lib/packages lib/python
-
-    lib/packages is for stuff we'll download; lib/python is to add
-    to our python path. We'll symlink python modules into lib/python.
-
-    At the time of release, patchwork depends on django version 1.5 or
-    later. Your distro probably provides this. If not, do a:
-
-      cd lib/packages
-      git clone https://github.com/django/django.git -b stable/1.5.x
-      cd ../python
-      ln -s ../packages/django/django ./django
-
-    The patchwork/settings/*.py files contain default settings for patchwork,
-    you'll need to configure settings for your own setup.
-
-    Rather than editing these files (which will cause conflicts when you
-    update the base patchwork code), create a file 'production.py', based on
-    the example:
-
-       cp patchwork/settings/production.example.py \
-          patchwork/settings/production.py
-
-    and override or add settings as necessary. You'll need to define the
-    following:
-
-      SECRET_KEY
-      ADMINS
-      DATABASES
-      TIME_ZONE
-      LANGUAGE_CODE
-      DEFAULT_FROM_EMAIL
-      NOTIFICATION_FROM_EMAIL
-
-    You can generate the SECRET_KEY with the following python code:
-
-      import string, random
-      chars = string.letters + string.digits + string.punctuation
-      print repr("".join([random.choice(chars) for i in range(0,50)]))
-
-    If you wish to enable the XML-RPC interface, add the following to
-    your local_settings.py file:
-
-      ENABLE_XMLRPC = True
-
-    Then, get patchwork to create its tables in your configured database:
-
-     PYTHONPATH=lib/python ./manage.py syncdb
-
-    and initialise the static content:
-
-     PYTHONPATH=lib/python ./manage.py collectstatic
-
-    You'll also need to load the initial tags and states into the
-    patchwork database:
-
-     PYTHONPATH=lib/python ./manage.py loaddata default_tags default_states
-
-    Finally, add privileges for your mail and web users. This is only needed if
-    you use the ident-based approach. If you use password-based database
-    authentication, you can skip this step.
-
-    Postgresql:
-      psql -f lib/sql/grant-all.postgres.sql patchwork
-
-    MySQL:
-      mysql patchwork < lib/sql/grant-all.mysql.sql
-
-
-3. Apache setup
-
-    Example apache configuration files are in lib/apache2/.
-
-    wsgi:
-
-        django has built-in support for WSGI, which supersedes the fastcgi
-        handler. It is thus the preferred method to run patchwork.
-
-        The necessary configuration for Apache2 may be found in
-
-         lib/apache2/patchwork.wsgi.conf.
-
-        You will need to install/enable mod_wsgi for this to work:
-
-         a2enmod wsgi
-         apache2ctl restart
-
-
-     mod_python:
-
-        An example apache configuration file for mod_python is in:
-
-          lib/apache2/patchwork.mod_python.conf
-
-        However, mod_python and mod_php may not work well together. So, if your
-        web server is used for serving php files, the fastcgi method may suit
-        instead.
-
-
-    fastcgi:
-
-        django has built-in support for fastcgi, which requires the
-        'flup' python module. An example configuration is in:
-
-          lib/apache2/patchwork.fastcgi.conf
-
-        - this also requires the mod_rewrite apache module to be loaded.
-
-        Once you have apache set up, you can start the fastcgi server with:
-
-          cd /srv/patchwork/
-          ./manage.py runfcgi method=prefork \
-                              socket=/srv/patchwork/var/fcgi.sock \
-                              pidfile=/srv/patchwork/var/fcgi.pid
-
-
-4. Configure patchwork
-    Now, you should be able to administer patchwork, by visiting the
-    URL:
-
-      http://your-host/admin/
-
-    You'll probably want to do the following:
-
-      * Set up your projects
-      * Configure your website address (in the Sites) section
-
-    
-5. Subscribe a local address to the mailing list
-
-    You will need an email address for patchwork to receive email on - for
-    example - patchwork@, and this address will need to be subscribed to the
-    list. Depending on the mailing list, you will probably need to confirm the
-    subscription - temporarily direct the alias to yourself to do this.
-
-
-6. Setup your MTA to deliver mail to the parsemail script
-
-    Your MTA will need to deliver mail to the parsemail script in the email/
-    directory. (Note, do not use the parsemail.py script directly). Something
-    like this in /etc/aliases is suitable for postfix:
-
-      patchwork: "|/srv/patchwork/patchwork/bin/parsemail.sh"
-
-    You may need to customise the parsemail.sh script if you haven't installed
-    patchwork in /srv/patchwork.
-
-    Test that you can deliver a patch to this script:
-
-     sudo -u nobody /srv/patchwork/patchwork/bin/parsemail.sh < mail
-
-
-7. Set up the patchwork cron script
-
-    Patchwork uses a cron script to clean up expired registrations, and
-    send notifications of patch changes (for projects with this enabled).
-
-    Something like this in your crontab should work:
-
-      # m h  dom mon dow   command
-      */10 * * * * cd patchwork; ./manage.py cron
-
-
-    - the frequency should be the same as the NOTIFICATION_DELAY_MINUTES
-    setting, which defaults to 10 minutes.
-
-
-8. Optional: Configure your VCS to automatically update patches
-
-    The tools directory of the patchwork distribution contains a file
-    named post-receive.hook which is an example git hook that can be
-    used to automatically update patches to the Accepted state when
-    corresponding comits are pushed via git.
-
-    To install this hook, simply copy it to the .git/hooks directory on
-    your server, name it post-receive, and make it executable.
-
-    This sample hook has support to update patches to different states
-    depending on which branch is being pushed to. See the STATE_MAP
-    setting in that file.
-
-    If you are using a system other than git, you can likely write a
-    similar hook using pwclient to update patch state. If you do write
-    one, please contribute it.
-
-
-Some errors:
-
-* __init__() got an unexpected keyword argument 'max_length'
-
- - you're running an old version of django. If your distribution doesn't
-   provide a newer version, just download and extract django into
-   lib/python/django
-
-* ERROR: permission denied for relation patchwork_...
-
- - the user that patchwork is running as (ie, the user of the web-server)
-   doesn't have access to the patchwork tables in the database. Check that
-   your web-server user exists in the database, and that it has permissions
-   to the tables.
-
-* pwclient fails for actions that require authentication, but a username
-  and password is given in ~/.pwclientrc. Server reports "No authentication
-  credentials given".
-
- - if you're using the FastCGI interface to apache, you'll need the
-   '-pass-header Authorization' option to the FastCGIExternalServer
-   configuration directive.
diff --git a/docs/development.md b/docs/development.md
new file mode 100644
index 0000000..a4eb321
--- /dev/null
+++ b/docs/development.md
@@ -0,0 +1,95 @@ 
+# Developing patchwork
+
+## Using virtualenv
+
+It's a good idea to use virtualenv to develop Python software. Virtual
+environments are "instances" of your system Python, without any of the
+additional Python packages installed. They are useful to develop and deploy
+patchwork against a "well known" set of dependencies, but they can also be
+used to test patchwork against several versions of Django.
+
+1. Install pip, virtualenv (python-pip, python-virtualenv packages)
+
+   Because we're going to recompile our dependencies, we'll also need
+   development headers. For the MySQL/MariaDB setups these are
+   `mariadb-devel` (Fedora), `libmysqlclient-dev` (Debian)
+
+2. Create a new virtual environement.
+
+   Inside a virtual env, we'll just install the dependencies needed for
+   patchwork and run it from there.
+
+       $ virtualenv django-1.8
+
+   This will create a virtual env called 'django-1.8' in eponymous directory.
+
+3. Activate a virtual environment
+
+       $ source django-1.8/bin/activate
+       (django-1.8)$
+
+   The shell prompt is preprended with the virtual env name.
+
+4. Install the required dependencies
+
+   To ease this task, it's customary to maintain a list of dependencies in a
+   text file and install them in one go. One can maintain such a list of
+   dependencies per interesting configuration.
+
+       (django-1.8)$ pip install -r docs/requirements-dev.txt
+
+   You will also need to install a version of Django - we don't install this
+   by default to allow development against multiple versions of Django. This
+   can be installed like so (assuming Django 1.8):
+
+       (django-1.8)$ pip install 'django<1.9,>=1.8'
+
+   Of course, this is a one-time step: once installed in the virtual
+   environment there is no need to to install requirements again.
+
+5. Run the development server
+
+       (django-1.8)$ ./manage.py --version
+       1.8
+       (django-1.8)$ ./manage.py runserver
+
+Once finished, you can kill the server (`Ctrl` + `C`) and exit the the virtual
+environment:
+
+    (django-1.8)$ deactivate
+    $
+
+Should you wish to re-enter this environment, simply source the `activate`
+script again.
+
+## Running Tests
+
+patchwork includes a [tox] script to automate testing. Before running this, you
+should probably install tox:
+
+    $ pip install tox
+
+You can show available
+targets like so:
+
+    $ tox --list
+
+You'll see that this includes a number of targets to run unit tests against the
+different versions of Django supported, along with some other targets related
+to code coverage and code quality. To run these, use the `-e` parameter:
+
+    $ tox -e py27-django18
+
+In the case of the unit tests targets, you can also run specific tests by
+passing the fully qualified test name as an additional argument to this
+command:
+
+    $ tox -e py27-django18 patchwork.tests.SubjectCleanUpTest
+
+Because patchwork support multiple versions of Django, it's very important
+that you test against all supported versions. When run without argument, tox
+will do this:
+
+    $ tox
+
+[tox]: https://tox.readthedocs.org/en/latest/
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..f79f84b
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,66 @@ 
+# patchwork
+
+patchwork is a patch tracking system for community-based projects. It is
+intended to make the patch management process easier for both the project's
+contributors and maintainers, leaving time for the more important (and more
+interesting) stuff.
+
+Patches that have been sent to a mailing list are 'caught' by the system, and
+appear on a web page. Any comments posted that reference the patch are appended
+to the patch page too. The project's maintainer can then scan through the list
+of patches, marking each with a certain state, such as Accepted, Rejected or
+Under Review. Old patches can be sent to the archive or deleted.
+
+Currently, patchwork is being used for a number of open-source projects, mostly
+subsystems of the Linux kernel. Although Patchwork has been developed with the
+kernel workflow in mind, the aim is to be flexible enough to suit the majority
+of community projects.
+
+# Download
+
+The latest version of Patchwork is available with git. To download:
+
+    $ git clone git://ozlabs.org/home/jk/git/patchwork
+
+Patchwork is distributed under the [GNU General Public License].
+
+# Design
+
+## patchwork should supplement mailing lists, not replace them
+
+Patchwork isn't intended to replace a community mailing list; that's why you
+can't comment on a patch in patchwork. If this were the case, then there would
+be two forums of discussion on patches, which fragments the patch review
+process. Developers who don't use patchwork would get left out of the
+discussion.
+
+However, a future development item for patchwork is to facilitate on-list
+commenting, by providing a "send a reply to the list" feature for logged-in
+users.
+
+## Don't pollute the project's changelogs with patchwork poop
+
+A project's changelogs are valuable - we don't want to add patchwork-specific
+metadata.
+
+## patchwork users shouldn't require a specific version control system
+
+Not everyone uses git for kernel development, and not everyone uses git for
+patchwork-tracked projects.
+
+It's still possible to hook other programs into patchwork, using the pwclient
+command-line client for patchwork, or directly to the XML RPC interface.
+
+# Getting Started
+
+You should check out the [installation] and [development] guides for
+information on how to get to work with patchwork.
+
+# Support
+
+All questions and contributions should be sent to the [patchwork mailing list].
+
+[GNU General Public License]: http://www.gnu.org/licenses/gpl-2.0.html
+[installation]: installation.md
+[development]: development.md
+[patchwork mailing list]: https://ozlabs.org/mailman/listinfo/patchwork
diff --git a/docs/installation.md b/docs/installation.md
new file mode 100644
index 0000000..6847b61
--- /dev/null
+++ b/docs/installation.md
@@ -0,0 +1,290 @@ 
+# Deploying Patchwork
+
+Patchwork uses the Django framework - there is some background on deploying
+Django applications here:
+
+    http://www.djangobook.com/en/2.0/chapter12/
+
+You'll need the following (applications used for patchwork development are
+in brackets):
+
+ * A Python interpreter
+ * [Django] >= 1.6. The latest version is recommended
+ * A webserver and suitable WSGI plugin. Options include [Apache] with the
+   [mod_python] plugin, or [Gunicorn] with [nginx] as the proxy server
+ * A database server (PostgreSQL, MySQL)
+ * Relevant Python modules for the database server (see the various
+   [requirements.txt] files)
+
+[Django]: https://www.djangoproject.com/
+[Apache]: http://httpd.apache.org/
+[mod_python]: http://modpython.org/
+[Gunicorn]: http://gunicorn.org/
+[nginx]: http://nginx.org/
+[requirements.txt]: ./docs
+
+## Database Configuration
+
+Django's ORM support multiple database backends, though the majority of testing
+has been carried out with PostgreSQL and MySQL.
+
+We need to create a database for the system, add accounts for two system users:
+the web user (the user that your web server runs as) and the mail user (the
+user that your mail server runs as). On Ubuntu these are `www-data` and
+`nobody`, respectively.
+
+As an alternative, you can use password-based login and a single database
+account. This is described further down.
+
+**NOTE:** For the following commands, a `$` prefix signifies that the command
+should be entered at your shell prompt, and a `>` prefix signifies the
+command-line client for your SQL server (`psql` or `mysql`).
+
+### Install Packages
+
+If you don't already have MySQL installed, you'll need to do so now. For
+example, to install MySQL on RHEL:
+
+    $ sudo yum install mysql-server
+
+### Create Required Databases and Users
+
+#### PostgreSQL (ident-based)
+
+PostgreSQL support [ident-based authentication], which uses the standard UNIX
+authentication method as a backend. This means no database-specific passwords
+need to be set/used. Assuming you are using this form of authentication, you
+just need to create the relevant UNIX users and database:
+
+    $ createdb patchwork
+    $ createuser www-data
+    $ createuser nobody
+
+[ident-based authentication]: http://www.postgresql.org/docs/8.4/static/auth-methods.html#AUTH-IDENT
+
+#### PostgreSQL (password-based)
+
+If you are not using the ident-based authentication, you will need to create
+both a new database and a new database user:
+
+    $ createuser -PE patchwork
+    $ createdb -O patchwork patchwork
+
+#### MySQL
+
+    $ mysql
+    > CREATE DATABASE patchwork CHARACTER SET utf8;
+    > CREATE USER 'www-data'@'localhost' IDENTIFIED BY '<password>';
+    > CREATE USER 'nobody'@'localhost' IDENTIFIED BY '<password>';
+
+### Configure Settings
+
+Once that is done, you need to tell Django about the new database settings,
+by defining your own `production.py` settings file (see below). For PostgreSQL:
+
+    DATABASES = {
+        'default': {
+            'ENGINE': 'django.db.backends.postgresql_psycopg2',
+            'HOST': 'localhost',
+            'PORT': '',
+            'USER': 'patchwork',
+            'PASSWORD': 'my_secret_password',
+            'NAME': 'patchwork',
+            'TEST_CHARSET': 'utf8',
+        },
+    }
+
+If you're using MySQL, only the `ENGINE` changes:
+
+    DATABASES = {
+        'default': {
+            'ENGINE': 'django.db.backends.mysql',
+            ...
+        },
+    }
+
+**NOTE:** `TEST_CHARSET` (`TEST/CHARSET` in Django >= 1.7) is used when
+creating tables for the test suite. Without it, tests checking for the correct
+handling of non-ASCII characters fail.
+
+## Django Setup
+
+### Configure Directories
+
+Set up some initial directories in the patchwork base directory:
+
+    mkdir -p lib/packages lib/python
+
+`lib/packages` is for stuff we'll download, `lib/python` is to add to our
+Python path. We'll symlink Python modules into `lib/python`.
+
+At the time of release, patchwork depends on Django version 1.6 or later.
+Where possible, try to use the latest stable version (currently 1.8). Your
+distro probably provides this. If not, install it manually:
+
+    cd lib/packages
+    git clone https://github.com/django/django.git -b stable/1.8.x
+    cd ../python
+    ln -s ../packages/django/django ./django
+
+### Configure Settings
+
+You will also need to configure a [settings] file for Django. A
+[sample settings file] is provided, which defines default settings for
+patchwork. You'll need to configure settings for your own setup and save this
+as `production.py` (or override the `DJANGO_SETTINGS_MODULE` environment
+variable).
+
+    cp patchwork/settings/production.example.py \
+      patchwork/settings/production.py
+
+At the very minimum, the following settings need to be configured:
+
+    SECRET_KEY
+    ADMINS
+    TIME_ZONE
+    LANGUAGE_CODE
+    DEFAULT_FROM_EMAIL
+    NOTIFICATION_FROM_EMAIL
+
+You can generate the `SECRET_KEY` with the following python code:
+
+    import string, random
+    chars = string.letters + string.digits + string.punctuation
+    print repr("".join([random.choice(chars) for i in range(0,50)]))
+
+If you wish to enable the XML-RPC interface, add the following to the file:
+
+    ENABLE_XMLRPC = True
+
+### Configure Database Tables
+
+Then, get patchwork to create its tables in your configured database. For
+Django 1.6 and below:
+
+    PYTHONPATH=../lib/python ./manage.py syncdb
+
+For Django 1.7+:
+
+    PYTHONPATH=../lib/python ./manage.py migrate
+
+Add privileges for your mail and web users. This is only needed if you use the
+ident-based approach. If you use password-based database authentication, you
+can skip this step.
+
+For Postgresql:
+
+    psql -f lib/sql/grant-all.postgres.sql patchwork
+
+For MySQL:
+
+    mysql patchwork < lib/sql/grant-all.mysql.sql
+
+### Other Tasks
+
+You will need to collect the static content into one location from which
+it can be served (by Apache or nginx, for example):
+
+    PYTHONPATH=lib/python ./manage.py collectstatic
+
+You'll also need to load the initial tags and states into the patchwork
+database:
+
+    PYTHONPATH=lib/python ./manage.py loaddata default_tags default_states
+
+[sample_settings_file]: ../patchwork/settings/production.example.py
+[settings]: https://docs.djangoproject.com/en/1.8/topics/settings/
+
+## Apache Setup
+
+Example apache configuration files are in `lib/apache2/`.
+
+### wsgi
+
+django has built-in support for WSGI, which supersedes the fastcgi handler. It is thus the preferred method to run patchwork.
+
+The necessary configuration for Apache2 may be found in:
+
+    lib/apache2/patchwork.wsgi.conf.
+
+You will need to install/enable mod_wsgi for this to work:
+
+    a2enmod wsgi
+    apache2ctl restart
+
+## Configure patchwork
+
+Now, you should be able to administer patchwork, by visiting the URL:
+
+    http://your-host/admin/
+
+You'll probably want to do the following:
+
+* Set up your projects
+* Configure your website address (in the Sites section of the admin)
+
+## Subscribe a Local Address to the Mailing List
+
+You will need an email address for patchwork to receive email on - for example
+- `patchwork@your-host`, and this address will need to be subscribed to the
+list. Depending on the mailing list, you will probably need to confirm the
+subscription - temporarily direct the alias to yourself to do this.
+
+## Setup your MTA to Deliver Mail to the Parsemail Script
+
+Your MTA will need to deliver mail to the parsemail script in the
+email/directory. (Note, do not use the `parsemail.py` script directly).
+Something like this in /etc/aliases is suitable for postfix:
+
+    patchwork: "|/srv/patchwork/apps/patchwork/bin/parsemail.sh"
+
+You may need to customise the `parsemail.sh` script if you haven't installed
+patchwork in `/srv/patchwork`.
+
+Test that you can deliver a patch to this script:
+
+    sudo -u nobody /srv/patchwork/apps/patchwork/bin/parsemail.sh < mail
+
+## Set up the patchwork cron script
+
+Patchwork uses a cron script to clean up expired registrations, and send
+notifications of patch changes (for projects with this enabled). Something like
+this in your crontab should work:
+
+    # m h  dom mon dow   command
+    */10 * * * * cd patchwork; ./manage.py cron
+
+The frequency should be the same as the `NOTIFICATION_DELAY_MINUTES` setting,
+which defaults to 10 minutes.
+
+## (Optional) Configure your VCS to Automatically Update Patches
+
+The tools directory of the patchwork distribution contains a file named
+`post-receive.hook` which is a sample git hook that can be used to
+automatically update patches to the `Accepted` state when corresponding
+commits are pushed via git.
+
+To install this hook, simply copy it to the `.git/hooks` directory on your
+server, name it `post-receive`, and make it executable.
+
+This sample hook has support to update patches to different states depending
+on which branch is being pushed to. See the `STATE_MAP` setting in that file.
+
+If you are using a system other than git, you can likely write a similar hook
+using `pwclient` to update patch state. If you do write one, please contribute
+it.
+
+Some errors:
+
+* `ERROR: permission denied for relation patchwork_...`
+  The user that patchwork is running as (i.e. the user of the web-server)
+  doesn't have access to the patchwork tables in the database. Check that your
+  web server user exists in the database, and that it has permissions to the
+  tables.
+
+* pwclient fails for actions that require authentication, but a username
+and password is given int ~/.pwclient rc. Server reports "No authentication
+credentials given".
+  If you're using the FastCGI interface to apache, you'll need the
+  `-pass-header Authorization` option to the FastCGIExternalServer
+  configuration directive.
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..ce60307
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,10 @@ 
+site_name: patchwork
+site_url: http://jk.ozlabs.org/projects/patchwork/
+site_description: patchwork - the web-based patch tracking system
+
+repo_url: git://ozlabs.org/home/jk/git/patchwork
+
+pages:
+ - Home: 'index.md'
+ - Installation: 'installation.md'
+ - Development: 'development.md'
diff --git a/patchwork/settings/production.example.py b/patchwork/settings/production.example.py
index fd0a1f6..7af79a7 100644
--- a/patchwork/settings/production.example.py
+++ b/patchwork/settings/production.example.py
@@ -50,7 +50,7 @@  DATABASES = {
 }
 
 #
-# Static files settings. Set this to the 
+# Static files settings
 # https://docs.djangoproject.com/en/1.7/ref/settings/#static-files
 #