Add documentation.

4 files changed, 67 insertions, 16 deletions

diff --git a/README.md b/README.md
index 79e3c1c6..7f54930a 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,7 @@
 # Python Discord: Site
 
-This is all of the code that is responsible for maintaining [our website](https://pythondiscord.com), and all of
-its subdomains.
+This is all of the code that is responsible for maintaining
+[our website](https://pythondiscord.com), and all of its subdomains.
 
-If you're looking to contribute or play around with the code, take a look at our 
-[Project Guide](https://wiki.pythondiscord.com/wiki/contributing/project/site), hosted on the wiki you'll find
-in this very repository.
\ No newline at end of file
+If you're looking to contribute or play around with the code,
+take a look at the [`docs` directory](docs).
diff --git a/SETUP.md b/SETUP.md
deleted file mode 100644
index dd974338..00000000
--- a/SETUP.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# Setting up & running up the website locally
-*to be put on the wiki*
-
-- `pipenv sync`
-- `psql -c 'CREATE USER pysite WITH CREATEDB;'`
-- `psql -c 'CREATE DATABASE pysite OWNER pysite;'`
-- `echo 'DEBUG=1' >> .env`
-- `echo 'DATABASE_URL=postgres://pysite:@localhost/pysite' >> .env`
-- `pipenv shell`
-- `python manage.py migrate`
-- `python manage.py runserver`
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..6bef9c3c
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,8 @@
+# Documentation
+This directory contains useful documentation for working with and using our site.
+
+## Table of contents
+* [Setup guide](setup.md)
+  * [PostgreSQL setup](setup.md#postgresql-setup)
+  * [Development with Docker](setup.md#development-with-docker)
+  * [Development with `pip`](setup.md#development-with-pip)
diff --git a/docs/setup.md b/docs/setup.md
new file mode 100644
index 00000000..16b27045
--- /dev/null
+++ b/docs/setup.md
@@ -0,0 +1,55 @@
+# Setup
+Setting up the Python site for local development is quick and easy using `pip`.
+Alternatively, you can set it up using Docker. Both of these methods are documented here.
+
+## Development with Docker
+To quickly set up the site locally, you can use Docker.
+You will need Docker itself and `docker-compose` - you can omit the latter if you want to
+use PostgreSQL on your host. Refer to the docker documentation on how to install Docker.
+
+If you want to set the site up using `docker-compose`, simply run
+```sh
+$ docker-compose up
+```
+and it will do its magic.
+
+Otherwise, you need to set a bunch of environment variables (or pass them along to
+the container). You will also need to have a running PostgreSQL instance if you want
+to run on your host's PostgreSQL instance.
+
+## PostgreSQL setup
+Install PostgreSQL according to its documentation. Then, create databases and users:
+```sql
+$ psql -qd postgres
+postgres=# CREATE USER pysite WITH CREATEDB;
+postgres=# CREATE DATABASE pysite OWNER pysite;
+```
+Using different databases for development and tests is recommended because Django
+will expect an empty database when running tests.
+Now that PostgreSQL is set up, simply set the proper database URL
+in your environment variables:
+```sh
+$ export DATABASE_URL=postgres://pysite@localhost/pysite
+```
+A simpler approach to automatically configuring this might come in the
+near future - if you have any suggestions, please let us know!
+
+
+## Development with `pip`
+This is the recommended way if you wish to quickly test your changes and don't want
+the overhead that Docker brings.
+
+Follow the PostgreSQL setup instructions above. Then, create a virtual environment
+for the project. If you're new to this, you may want to check out [Installing packages
+using pip and virtualenv](https://packaging.python.org/guides/installing-using-pip-and-virtualenv/)
+from the Python Packaging User Guide.
+
+Enter the virtual environment. Now you can run
+```sh
+$ pip install -e .[lint,test]
+```
+to install base dependencies along with lint and test dependencies.
+
+You can either use `python manage.py` directly, or you can use the console
+entrypoint for it, `psmgr`. For example, to run tests, you could use either
+`python manage.py test` or `psmgr test`. Happy hacking!