docs: Rewrite documentation

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.

Acked-by: Damien Lespiau <damien.lespiau@intel.com>
Signed-off-by: Stephen Finucane <stephen.finucane@intel.com>
Signed-off-by: Damien Lespiau <damien.lespiau@intel.com>

1 files changed, 0 insertions, 305 deletions

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.