From 092d0b013b297f987718f42d2779e4c44239dfd2 Mon Sep 17 00:00:00 2001
From: Tom Willemse
Date: Mon, 16 Dec 2013 01:26:56 +0100
Subject: Add some docs

---
 docs/index.rst | 106 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 106 insertions(+)
 create mode 100644 docs/index.rst

(limited to 'docs/index.rst')

diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..b46e4b8
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,106 @@
+.. topple documentation master file, created by
+   sphinx-quickstart on Sun Dec 15 23:37:44 2013.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+topple
+======
+
+Bigger projects cat get somewhat more complicated settings files. One
+strategy from keeping required settings and installation-specific
+settings apart may be to separate the two in different files. Whether
+this is the case or not, topple might be able to help you.
+
+topple tries to help you maintain this kind of file by allowing you to
+specify a template of such a file, with some extra data such as a
+predicate to check the value with, and generating and updating such
+files from this template.
+
+Configuration
+-------------
+
+Configuration is stored in a module named ``toppler``, unless a
+``--module`` or ``-m`` argument was specified on the command line. An
+example configuration might look like::
+
+  def boolp(val):
+      return isinstance(val, bool)
+  def integerp(val):
+      return isinstance(val, integer)
+  def stringp(val):
+      return isinstance(val, string)
+  def listp(val):
+      return isinstance(val, list)
+
+  OUTPUT_FILE = 'settings_local.py'
+  SETTINGS = [
+      ('DEBUG', (boolp, True)),
+      ('DEBUG_PROPOGATE_EXCEPTIONS', (boolp, True)),
+      ('SITE_ID', (integerp, 1)),
+      ('ALLOWED_HOSTS', (listp, ['.example.com']))
+  ]
+
+This file specifies a few predicates to check the types of the
+settings. Any function returning a ``True`` or ``False`` value and
+taking a single arguments (the value specified for the setting) can be
+used. For example ``os.path.exists`` may be used to specify that the
+value in a setting must be an existing path. It specifies that the
+settings should be output to the file ``settings_local.py`` and that
+it should have the ``DEBUG``, ``DEBUG_PROPOGATE_EXCEPTIONS``,
+``SITE_ID`` and ``ALLOWED_HOSTS`` settings. It also specifies the
+predicates to use to check the validity of each setting and their
+initial values.
+
+Command-line Usage
+------------------
+
+topple works through three main commands, ``generate``, ``update`` and
+``check``. These commands are implemented by the following classes:
+
+.. class:: Generate
+
+   Implements the ``generate`` command. This command turns the
+   template as found in the configuration file into a usable settings
+   file. The predicates aren't used at this point, it is not required
+   to specify valid options in the template, though it is important
+   for you to change these settings as soon as possible, otherwise you
+   won't be able to (fully) use the settings.
+
+   The ``generate`` command writes the settings to the ``OUTPUT_FILE``
+   as specified in the configuration file, unless the ``--preview`` (or
+   ``-p``) option is given, in which case the settings are printed to
+   the standard output stream.
+
+.. class:: Update
+
+   Implements the ``update`` command. This command reads the existing
+   ``OUTPUT_FILE`` and the configuration and merges them. It leaves
+   existing settings as they are, but adds settings that are not yet
+   present in the ``OUTPUT_FILE``.
+
+   The ``update`` command writes the settings to the ``OUTPUT_FILE``
+   as specified in the cunfiguration file, unless the ``--preview``
+   (or ``-p``) option is given, in which case the settings are printed
+   to the standard output stream.
+
+.. class:: Check
+
+   Implements the ``check`` command. This command reads the existing
+   ``OUTPUT_FILE`` and the configuration and checks the validity of
+   the settings in ``OUTPUT_FILE``. For each setting that doesn't
+   match the given predicate an error message is printed, specifying
+   the setting, value and name of the predicate. For each setting that
+   has been specified in the configuration file that wasn't found in
+   the ``OUTPUT_FILE`` a message is printed stating that it is missing
+   from the ``OUTPUT_FILE``.
+
+.. toctree::
+   :maxdepth: 2
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`
-- 
cgit v1.2.3-54-g00ecf