config doc

fixes #4

doc/source/install.rst

@@ -44,3 +44,90 @@ For larigira, you need to set the ``MPD_HOST`` environment variable to
         raise CommandError(error)
     mpd.CommandError: [400] {addid} Access denied
 
+
+
+Options
+~~~~~~~~~~
+
+Options will be presented "grouped" to make them more easily understandable. This is just for documentation
+purposes, they don't need to be divided in the configuration.
+
+Options values are assumed to be JSON formatted. For strings and numbers, this makes no difference. For
+booleans, this means that the only valid values are ``true`` and ``false``. For lists and objects, read a JSON
+reference or learn from examples.
+
+To set an option, you must set an environment variable with the name ``LARIGIRA_OPTIONNAME``.
+
+General
+^^^^^^^^^^^^^
+
+MPD_HOST
+    This option let you set the way to connect to your MPD server. Please remind that for complete larigira
+    operatoin you should set the path to a UNIX domain socket, not ``localhost``
+MPD_PORT
+    If you are not using a socket, but a TCP address (which is *not* suggested), this is how you can specify the
+    port.
+DEBUG
+    you can set it to ``true`` or ``false``. Defaults to ``false``.
+TMPDIR
+    The base for larigira tmpdir. Please note that larigira will create its own directory inside this
+    temporary directory. This defaults to the system-wide ``$TMPDIR``, or to ``/tmp/`` if not ``TMPDIR`` is
+    not set. Choose it wisely, keeping in mind that in this directory a lot of cache files will be stored, and
+    could therefore require hundreds of MB.
+
+Events
+^^^^^^^^^
+
+CONTINOUS_AUDIOSPEC
+    when the playlist is too short, larigira picks something new. How? this is controlled by this variable.
+    This variable should be set to the JSON representation of an audiospec describing how to generate new
+    audios. The default is ``{"kind": "mpd", "howmany": 1}``. You could, for example, change it to
+    ``{ "kind": "randomdir", "paths": ["/var/music"], "howmany": 10}``
+EVENT_FILTERS
+    See :doc:`eventfilters`
+LOG_CONFIG
+    Path to an INI-formatted file to configure logging. See `python logging documentation
+    <https://docs.python.org/2/library/logging.config.html#logging-config-dictschema>`_
+
+Internals
+^^^^^^^^^^^^^^
+
+These are options you probably don't want to change, unless you want to debug
+
+CACHING_TIME
+    larigira needs an estimate on how much time an audiogenerator will need. This option sets this. The
+    default is 10 (seconds). If you set it too low, the events will be scheduled with some delay
+CHECK_SECS
+    The interval (in seconds) that will trigger a check for the playlist length. Set it too low, and you'll be
+    consuming resource with no usage. Set it too high and you might miss some moment of playlist shortage.
+    The default is 20
+EVENT_TICK_SECS
+    The interval (in seconds) that will trigger a check on the events to see if there's something to schedule.
+    This also determines how much time in advance you can add/delete/change an event for the change to be
+    effective.
+SCRIPTS_PATH
+    This options controls the path where scripts will be looked for. This is a single path, not a list. The
+    default is ``$XDG_CONFIG_DIR/larigira/scripts/`` which might boil down to
+    ``$HOME/.config/larigira/scripts/`` 
+DB_URI
+    The path to the events database. The default is ``$XDG_CONFIG_DIR/larigira/db.json``
+MPD_WAIT_START
+    When larigira starts, it will try to connect to MPD. If MPD doesn't look ready, larigira will wait until
+    it is. This makes larigira depend on MPD. However, this also makes it easier to run larigira at boot
+    without complex dependency on MPD to be fully started and listening. You can disable this behavior setting
+    this to ``false``
+MPD_WAIT_START_RETRYSECS
+    The behavior described for the previous option requires polling. This variable lets you customize the
+    polling frequency, expressed in seconds. The default is ``5``.
+
+Web interface
+^^^^^^^^^^^^^^^^
+
+FILE_PATH_SUGGESTION
+    A list of paths. Those paths will be scanned for suggestions in audiogenerator forms.
+UI_CALENDAR_FREQUENCY_THRESHOLD
+    The "calendar" view in the UI will omit events that occur too frequently, to avoid noise. This variable is
+    the threshold, in seconds. Defaults to 4 hours.
+BOOTSTRAP_SERVE_LOCAL
+    larigira can serve every js and css by itself. However, you might like to make the user download standard
+    libraries from CDNs. In that case, set this variable to ``false``.