Merge pull request #381 from CTPUG/docs

Document settings

docs/index.rst

@@ -1,8 +1,3 @@
-.. wafer documentation master file, created by
-   sphinx-quickstart on Thu Oct  9 22:34:22 2014.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Welcome to wafer's documentation!
 =================================
 
@@ -17,7 +12,7 @@ Contents:
    sponsors
    schedule
    static
-
+   settings
 
 
 Indices and tables
@@ -26,4 +21,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

docs/install.rst

@@ -5,26 +5,18 @@ Installation
 Supported versions
 ==================
 
-Wafer supports Django 1.8 and 1.9 and python 2.7, 3.4 and 3.5.
+Wafer supports Django 1.8-1.11 and Python 2.7, 3.4-3.6.
 
 Requirements
 ============
 
-In addition to Django, wafer requires:
+In addition to Django, wafer has some requirements on external
+libraries. They're listed in ``setup.py``.
 
-* django-crispy-forms
-* django-registration-redux
-* pyLibravatar
-* django-medusa
-* django-markitup
+Basic Dev install
+=================
 
-and their dependancies.
-
-Basic instructions
-==================
-
-
-#. Install all the dependancies
+#. Install all the dependencies
    ``pip install -r requirements.txt``
 
 #. Create the initial database schema
@@ -42,7 +34,7 @@ Basic instructions
 
    * By default, wafer assumes that the site will be accessible over ssl,
      so the registration emails will use an 'https' prefix. If this
-     is not the case, override the wafer/registration/activation_email.txt
+     is not the case, override the ``wafer/registration/activation_email.txt``
      template.
 
 #. Wafer uses the Django caching infrastructure in several places, so
@@ -57,12 +49,24 @@ Basic instructions
 
 #. Have a fun conference.
 
-Important settings
-==================
+Recommended production setup
+============================
+
+#. Create a new Django app, in your own VCS repository. Add wafer
+   (probably pinned) as a requirement.
+
+#. Include wafer's ``wafer.settings`` in your ``settings.py``::
 
-``TALKS_OPEN`` controls whether talk submissions are accepted. Set to False to close talk submissions.
+       from wafer.settings import *
 
-``WAFER_MENUS`` adds the top level menu items for the site. 
+       TIME_ZONE = 'Africa/Johannesburg'
+       ...
 
+#. You'll want to include wafer's default values for some settings, e.g.
+   ``INSTALLED_APPS``, rather than completely overriding them.
+   See :ref:`settings` for the wafer-specific settings.
 
+#. Override templates as necessary, by putting your own templates
+   directory early in ``TEMPLATES``.
 
+#. And then continue with the basic instructions above.

docs/settings.rst

@@ -0,0 +1,143 @@
+.. _settings:
+
+--------
+Settings
+--------
+
+Wafer has several Django settings that control its behaviour.
+It attempts to provide reasonable defaults for these, (and Django in general),
+in the ``wafer.settings`` module, so you can import this in your app's
+``settings.py``, and then override things you want to change.
+
+
+Wafer's settings
+================
+
+``PAGE_DIR``
+    The directory that the ``load_pages`` management command will load
+    pages from.
+    Should be an absolute path with a trailing ``/``.
+
+``TALKS_OPEN``
+    Controls whether talk submissions are accepted.
+    Set to ``False`` to close talk submissions.
+
+``WAFER_CACHE``
+    The name of the Django cache backend that wafer can use.
+    Defaults to ``'wafer_cache'``.
+
+``WAFER_DEBIAN_NM_API_KEY``
+    The API Key for ``nm.debian.org``'s API, used by Debian SSO.
+    Used when ``WAFER_SSO`` contains ``'debian'``.
+
+``WAFER_DYNAMIC_MENUS``
+    A list of functions to call to generate additional menus.
+
+``WAFER_GITHUB_CLIENT_ID``
+    The client ID for GitHub SSO.
+    Used when ``WAFER_SSO`` contains ``'github'``.
+    If you set this up, they'll provide you with one.
+
+``WAFER_GITHUB_CLIENT_SECRET``
+    The secret for GitHub SSO.
+    Used when ``WAFER_SSO`` contains ``'github'``.
+    If you set this up, they'll provide you with one.
+
+``WAFER_HIDE_LOGIN``
+    A boolean flag.
+    When ``True``, the login link in the menu is hidden.
+    This is useful to set, before making a site static.
+
+``WAFER_SSO``
+    A list of SSO mechanisms in use.
+    Possible options are: ``'debian'``, ``'github'``.
+
+``WAFER_TALK_FORM``
+    The form used for talk/event submission.
+    There is a reasonable default form, but this can be changed to
+    customise the submission process.
+
+``WAFER_MENUS``
+    Static menu structure for the site.
+    This is a list of dicts, with the keys:
+
+    ``label``
+        The text in the menu.
+
+    ``url``
+        The URL to link to.
+
+    ``items``
+        An optional list of similar dicts, making up a submenu.
+
+``WAFER_PUBLIC_ATTENDEE_LIST``
+    A boolean flag.
+    When ``True``, all registered users' profiles are publicly visible.
+    Otherwise, only users with associated public talks have public
+    profiles.
+
+``WAFER_REGISTRATION_FORM``
+    A Django Form used for KV registration.
+    Used when ``WAFER_REGISTRATION_MODE`` is set set to ``'form'``.
+
+``WAFER_REGISTRATION_MODE``
+    The mechanism wafer will use to decide if an attendee is registered.
+    The default is ``'ticket'`` for Quicket integration.
+
+``WAFER_REGISTRATION_OPEN``
+    A boolean flag.
+    When ``True``, users can register for the conference.
+    (Note, this is not the same as signing up for an account on the website.)
+
+``WAFER_TALKS_OPEN``
+    A boolean flag.
+    When ``True``, users can submit talks.
+
+``WAFER_TICKETS_SECRET``
+    The secret for the Quicket API.
+    Used when ``WAFER_REGISTRATION_MODE`` is ``'ticket'``.
+
+``WAFER_VIDEO``
+    A boolean flag.
+    When ``True``, the default talk submission form will ask for a video
+    release from the submitter.
+
+``WAFER_VIDEO_REVIEWER``
+    A boolean flag.
+    When ``True``, the default talk submission form will ask for the
+    email address of someone who will review the talk's video, once it
+    is ready to publish.
+
+
+Third party settings
+====================
+
+Some libraries that wafer uses have settings that you may want to
+configure.
+This is a non-complete list of them, see the individual project's
+documentation for more details.
+
+``ACCOUNT_ACTIVATION_DAYS``
+    Used by `django-registration-redux`_.
+    Number of days that users have to click the account activation link
+    that was emailed to them.
+
+``MARKITUP_FILTER``
+    Configuration for `django-markitup`_.
+    The type of markup used for pages, talk abstracts, user profiles,
+    and other things.
+    Also, configuration for the conversion, such as allowing arbitrary
+    HTML embedding.
+
+``MEDUSA_DEPLOY_DIR``
+    Used by `django-medusa`_.
+    The directory that static versions of the sites are rendered to.
+
+``REGISTRATION_OPEN``
+    Boolean flag.
+    Used by `django-registration-redux`_.
+    When ``True``, user sign-up is permitted.
+
+.. _django-markitup: https://github.com/zsiciarz/django-markitup
+.. _django-medusa: https://github.com/mtigas/django-medusa/
+.. _django-registration-redux: https://django-registration-redux.readthedocs.io/