WIP: Expand docs

.gitignore

@@ -1 +1,2 @@
 .coverage
+site

Makefile

@@ -23,6 +23,8 @@ test:
 	@isort --check ${RESULT}
 	@echo -e "\n${PURPLE}Check for missing migrations:${RESET}"
 	@example/manage.py makemigrations --check --dry-run ${RESULT}
+	@echo -e "\n${PURPLE}Check docs build:${RESET}"
+	@mkdocs build --strict ${RESULT}
 
 release:
 	python setup.py sdist bdist_wheel

docs/contribution.md

@@ -0,0 +1,113 @@
+# Contribution
+
+You can find the [source code for django-conman][github-repo] on github.
+
+We gratefully welcome contributions, be they bug reports, code, reviews,
+documentation, or any other constructive assistance.
+
+## Tests
+
+In order to help keep the code reliable we automatically run a test suite
+against the changes whenever a commit is pushed to the github repo.
+
+!!! Note
+    For your convenience, it's probably a good idea to run the tests locally
+    before submitting a pull request for approval. The tests can be run locally
+    in a few seconds, but it can take minutes for the results to show up on
+    github. This may save you a lot of bother if/when they fail. If you're
+    having issues getting the tests to pass, submit the PR, and we may be able
+    to help.
+
+
+### Local testing
+
+The test suite depends on Python 3 and expects PostgresQL. To run the tests
+locally:
+
+1. Clone the git repo:
+
+        git clone git@github.com:meshy/django-conman.git
+
+1. Set up a python virtual environment (we recommend
+   [virtualenvwrapper][virtualenvwrapper]) and install the required python
+   packages:
+
+        cd django-conman
+        mkvirtualenv django-conman -p $(which python3)
+        pip install -r requirements.txt
+
+1. The tests assume you're running [PostgresQL locally without a
+   password][postgres-without-passwords]. If you need to override this, you can
+   set the `DATABASE_URL` environment variable as accepted by
+   [dj-database-url][dj-database-url].
+
+1. Finally, you should be able to run the tests with:
+
+        make test
+
+!!! Note
+    There is one minor difference between local tests and those run against
+    pull-requests: we do not enforce the errors thrown by
+    [flake8-docstrings][flake8-docstrings], we only run the check locally to
+    encourage thorough documentation.
+
+
+## Code style
+
+Hopefully, adherence to a code style will keep our codebase in good shape for
+as long as possible.
+
+!!! Note
+    We endeavour to avoid use of `#noqa` or other methods of dodging the code
+    quality checks, and we're keen to retain our 100% test coverage. Apologies
+    if this appears to be a little draconian.
+
+### Python
+
+Python code should adhere to [PEP8][pep8]. We also have a couple of other
+eccentricities. Please:
+
+- Try to stick to the "max 80 chars per line" rule. We have some flexibility,
+  but our linter will start to complain at 90 chars. If you're going over that,
+  there's probably a nicer way to structure the logic. Do not wrap long lines
+  with `\` (backslash).
+
+- Make multi-line lists have one element per line, and a trailing comma. Indent
+  the elements by four spaces instead of aligning with the brace.
+
+        nice_things = [
+            'long lists with one element per line',
+            'four space indents',
+            'trailing commas',
+        ]
+
+- Keep imports in order: future, core library, 3rd party, 1st party, then
+  relative. Rather than bother to do this by hand, we recommend [isort][isort].
+
+- When in doubt, keep things in alphabetical order.
+
+### Automation
+
+As well as running continuous integration tests, we automate the process
+of checking adherence to our style guide where possible.
+
+There are a couple of tools we recommend to make things easier:
+
+- [EditorConfig][editorconfig]: This helps to normalise simple issues like
+  how many spaces constitute a tab, clearing whitespace at the end of lines,
+  and missing newlines at the end of files. Most people should find there is a
+  plugin for their editor.
+
+- [isort][isort]: This simplifies the process of keeping the imports in order.
+  To automatically sort all imports before committing, run `isort --apply`.
+  There are a number of editor plugins available, if you prefer.
+
+
+[dj-database-url]: https://github.com/kennethreitz/dj-database-url
+[editorconfig]: http://editorconfig.org/
+[flake8-docstrings]: https://pypi.python.org/pypi/flake8-docstrings
+[github-repo]: https://github.com/meshy/django-conman
+[isort]: https://github.com/timothycrosley/isort
+[pep8]: https://www.python.org/dev/peps/pep-0008/
+[postgres-without-passwords]: http://meshy.co.uk/posts/postgresql-without-passwords
+[virtualenvwrapper]: https://pypi.python.org/pypi/virtualenvwrapper

docs/index.md

@@ -1,32 +1,88 @@
 # Django Conman
 
-Django Conman is a lightweight content management library for [Django](https://www.djangoproject.com/). It has a very modular structure to allow you to pick-and-choose only the features you need for your site.
+Conman is a lightweight content management library for [Django][django].
 
-## Quick Start
+It allows you to manage your site's URLs in the database, but doesn't dictate
+the shape of your data. Instead, you create types of content that can be
+associated with the URLs, and views to display them. This leads to a little
+extra setup, but is very flexible.
 
-* Install Conman: `pip install django-conman`
-* Add your chosen Conman modules and [Django Polymorhpic](https://django-polymorphic.readthedocs.org/en/latest/) to `INSTALLED_APPS`:
+## Requirements
 
-```python
-INSTALLED_APPS = (
-    'conman.routes',
-    'conman.redirects',
+- **Python 3.4+**. Python 2 is **not** supported.
+- **Django 1.10+**. Support will only continue for [versions that are supported
+  upstream][django-supported-versions].
 
-    'polymorphic',
+## Installation & configuration
 
-    ...
-)
+### Installation
+
+The most reliable way to install the latest version of django-conman is to use
+[pip][pip] to install from [PyPI][pypi]:
+
+```bash
+pip install django-conman
 ```
 
-* Add Conman to your base `urls.py` after all other urls:
+If you wish to test out the latest development version instead, you can
+install directly from [the github repo][github-repo]:
+
+```bash
+pip install -e git+https://github.com/meshy/django-conman.git#egg=django-conman
+```
+
+### URL configuration
+
+Add to your root `urls.py` after all other urls:
 
 ```python
 urlpatterns = [
-    ...
-
     # Must be last to avoid conflicting with other urls.
     url(r'', include('conman.routes.urls')),
 ]
 ```
 
-* Ensure the Conman database tables exist: `python manage.py migrate`
+### Settings
+
+
+Add Conman and [Django Polymorhpic][django-polymorphic] to `INSTALLED_APPS`.
+
+```python
+INSTALLED_APPS += (
+    'conman.routes',
+    'conman.redirects',  # Optional, see below.
+    'polymorphic',
+)
+```
+!!! Note
+    For more information about `'conman.redirects'`, see the [Redirects topic
+    guide](/topics/redirects.md).
+
+    You are likely to be adding more apps here, as few `Route` subclasses are
+    provided out of the box. See the [Routes topic guide](/topics/routes.md).
+
+    To create your own, see the [Creating custom
+    routes](/tutorials/custom_routes.md) tutorial.
+
+
+### Migrations
+
+Create the database tables:
+
+```bash
+python manage.py migrate
+```
+
+### Admin integration
+
+If you're using django's admin, see the [Admin integration topic
+guide](/topics/admin.md).
+
+
+[content-types]: https://docs.djangoproject.com/en/stable/ref/contrib/contenttypes/
+[django]: https://www.djangoproject.com/
+[django-polymorphic]: https://django-polymorphic.readthedocs.org/en/latest/
+[django-supported-versions]: https://www.djangoproject.com/download/#supported-versions
+[github-repo]: https://github.com/meshy/django-conman
+[pip]: https://pip.pypa.io/en/latest/
+[pypi]: https://pypi.python.org/

docs/recipes/breadcrumbs.md

@@ -0,0 +1,14 @@
+# Breadcrumbs
+
+To add breadcrumbs to your page, add the following to your template:
+
+```django
+{% for ancestor in route.get_ancestors %}
+    <a href="{{ ancestor.get_absolute_url }}">
+        {{ ancestor }}
+    </a>
+{% endfor %}
+<span>{{ route }}</span>
+```
+
+Styling the links is left as an exercise for the reader.

docs/recipes/navigation.md

@@ -0,0 +1,47 @@
+# Navigation
+
+Let's assume you have created a subclass of `Route` called `Page`, and you want
+to use a list of these pages as the main navigation of your website.
+
+You will need to add this list to the context to every page. The best way to do
+this is with a [template context processor][context-processor]. Let's make one
+of those:
+
+```python
+# example_module/context_processors.py
+from example_module.models import Page
+
+def nav_pages(request):
+    return {'nav_pages': Page.objects.with_level(1)}
+
+
+# settings.py
+TEMPLATES['OPTIONS']['context_processors'].append(
+    'example_module.context_processors.nav_pages'
+)
+```
+
+The [`with_level(1)`](/reference/route.md#with_level) call we make here limits
+the items in the queryset down to those on the first level of navigation. It
+does not include the `Route` with `url='/'`.
+
+!!! Note
+    You also probably don't really want to use `.append` on your `TEMPLATES`
+    setting like this. It would be better to add to the appropriate place where
+    it's already defined. We've just done it like this for brevity.
+
+
+Now that this has been exposed to the templates, we can add the pages into the
+navigation in your base template:
+
+```django
+<nav>
+    {% for page in nav_pages %}
+        <a href="{{ page.get_absolute_url }}">
+            {{ page }}
+        </a>
+    {% endfor %}
+</nav>
+```
+
+[context-processor]: https://docs.djangoproject.com/en/stable/ref/templates/api/#writing-your-own-context-processors

docs/reference/handlers.md

@@ -0,0 +1,59 @@
+# Handlers
+
+The base class for handlers is `BaseHandler`. For information on the existing
+handlers, see [Handlers (topic guide)](/topics/handlers.md).
+
+
+## Methods
+
+###  `__init__`
+
+Signature: `__init__(self, route)`
+
+When instantiating a subclass of `BaseHandler`, `route` is a required argument.
+This is then saved on the instance as `self.route`, and can be used later from
+`handle`.
+
+### `handle`
+
+Signature: `handle(self, request, path)`
+
+Called when someone browses to a `Route`.
+
+Just like a django view, `handle` accepts `request` and is expected to return
+an [`HttpResponse`][django-response].
+
+The `path` is relative to the URL of `self.route` (but it will always have a
+leading `/`). For example, if the only `Route` in the DB is this one...
+
+```python
+route = Route.objects.create(url='/projects/')
+```
+
+...then when someone browses to `/projects/conman/`, this method would be
+called with `path='/conman/'`.
+
+!!! Note
+    The `TemplateHandler` and `ViewHandler` raise a `Resolver404` if the `path`
+    is anything other than `/`, but the `URLConfHandler` has the ability to
+    deal with other subpaths.
+
+    See [Handlers (topic guide)](/topics/handlers.md).
+
+
+## Class methods
+
+### `check`
+
+Signature: `check(cls, route)`
+
+Route-subclasses delegate [model-level checks][django-checks] to this method on
+their `handler_class`.
+
+This allows handlers to check that their associated `Route` objects are
+correctly configured. For example, `TemplateHandler` checks that a
+`template_name` attribute exists on associated `Route` subclasses.
+
+
+[django-checks]: https://docs.djangoproject.com/en/stable/topics/checks/#field-model-manager-and-database-checks
+[django-response]: https://docs.djangoproject.com/en/stable/topics/http/views/