Update docs for configurations / layout changes

Also fixup a bit about requirements.txt files (which are gone)

docs/admin/install.rst

@@ -5,3 +5,22 @@
 FIXME: This needs to be written. For now, you can look at the
 :ref:`hacking-chapter`, use postgresql and skip the things that are
 development-environment specific.
+
+Settings
+------------
+
+richard relies extensively on environment settings which **will not work with
+Apache/mod_wsgi setups**.
+
+For configuration purposes, the following table maps the 'richard'
+environment variables to their Django setting:
+
+======================================= =========================== ============================================== ===========================================
+Environment Variable                    Django Setting              Development Default                            Production Default
+======================================= =========================== ============================================== ===========================================
+DJANGO_DATABASES                        DATABASES                   See code                                       See code
+DJANGO_DEBUG                            DEBUG                       True                                           False
+DJANGO_SECRET_KEY                       SECRET_KEY                  secret-value                                   raises error
+RICHARD_API                             API                         True                                           False
+RICHARD_SITE_URL                        SITE_URL                    http://127.0.0.1:8000                          http://127.0.0.1:8000
+======================================= =========================== ============================================== ===========================================

docs/contributors/dev_layout.rst

@@ -7,13 +7,14 @@ directory tree like this::
 
    richard
    |- docs/          -- documentation
-   |- requirements/  -- requirements files for pip
-   \- richard/       -- richard django project
-      |- base/       -- base code shared by the other apps
-      |- pages/      -- code for "about", "contac", etc pages
-      |- sampledata/ -- code for loading sampledata from apps
-      |- sitenews/   -- code for sitenews
-      \- videos/     -- code for videos and search
+   |-src/
+     \- richard/       -- richard django project
+         |- base/       -- base code shared by the other apps
+         |- config/     -- settings and configuration
+         |- pages/      -- code for "about", "contac", etc pages
+         |- sampledata/ -- code for loading sampledata from apps
+         |- sitenews/   -- code for sitenews
+         \- videos/     -- code for videos and search
 
 
 Here's what's there:
@@ -23,12 +24,7 @@ Here's what's there:
     Documentation for the project build wtih Sphinx and formatted in
     restructuredtext.
 
-**richard/requirements/**
-
-    ``.txt`` files that you use with pip to install richard's
-    requirements.
-
-**richard/richard/**
+**src/richard/**
 
     This is the "Django project" part of the project and where the
     "Django apps" go. There are a few:
@@ -39,6 +35,10 @@ Here's what's there:
         central to the Django project. Middleware, context processors,
         base templates, static assets, etc.
 
+    **config**
+
+        This is where the settings and wsgi files live.
+
     **pages**
 
         Like django.contrib.flatpages except that nothing is in the

docs/contributors/dev_resources.rst

@@ -17,22 +17,18 @@ Project scaffolding
 Settings
 --------
 
-`<https://docs.djangoproject.com/en/dev/topics/settings/#django.conf.settings.configure>`_
-talks about settings, but doesn't cover separating settings into
-multiple settings files.
+richard has migrated to
+`django-configurations <http://django-configurations.readthedocs.org/>`_
+which makes settings in Django behave more like regular old class inheritance.
+The classes ``Base``, ``Testing``, ``Dev`` and ``Prod`` in the ``settings.py``
+module all handle the expected domains. You can override these by:
 
-richard uses ``settings_local.py`` for locally overriding settings
-defaults. Also, James Bennett talks about using ``local_settings.py`` in
-"Practical Django Projects" [PDP2009] which is essentially the same,
-but with a slightly different name. I like ``settings_local.py``
-better than ``local_settings.py`` since then all my settings files
-get listed next to each other when sorted alphabetically.
-
-.. [PDP2009] Practical Django Projects, by James Bennett
-
-For tests, richard uses ``settings_test.py`` which allows us to
-override settings explicitly for the test environment. We do this at
-Mozilla and it makes things a lot easier.
+* creating a ``settings_local.py`` file
+* ``from . import settings``
+* creating your class (or creating a Dev / Prod class) and extending from
+  ``settings.Base``
+* Updating your deployment scripts to run ``manage.py --settings
+  richard.config.settings_local``
 
 
 Requirements / environments / deployment
@@ -44,19 +40,10 @@ Requirements / environments / deployment
   richard uses virtualenv and pip to build the environment for richard
   to run.
 
-  Requirements are listed in ``requirements/`` in multiple files. The
-  base requirements are in ``requirements/base.txt`` and other
-  use-oriented requirements files include that and then add additional
-  requirements. This makes it easier to specify different kinds of
-  environments like development and deployment.
-
-  pip reads the requirements files, downloads requirements, and installs
-  them into the virtual environment.
-
-  It works pretty well except when PyPI is down.
-
-  We may revisit this later if this becomes an annoying problem.
-
+  Requirements are listed in the ``setup.py`` with ``extra_requires`` defined
+  for local development and postgres. Since richard is meant for deployment
+  rather than a framework, requirements are pinned hard. This makes it easy to
+  install various options without having multiple requirements files.
 
 Documentation
 -------------