config docs

1 files changed, 111 insertions, 85 deletions

diff --git a/docs/source/configuration/index.rst b/docs/source/configuration/index.rst
index ddf639a8..70de6572 100644
--- a/docs/source/configuration/index.rst
+++ b/docs/source/configuration/index.rst
@@ -12,6 +12,7 @@ Config options
 
 .. include:: alotrc_table.rst
 
+.. _account:
 
 Accounts
 ========
@@ -47,18 +48,59 @@ The following entries are interpreted at the moment:
 .. include:: accounts_table.rst
 
 
+Contacts Completion
+===================
+In each :ref:`account` section you can specify a `abook_command` that
+is considered the address book of that account and will be used
+for address completion where appropriate.
+
+This shell command will be called with the search prefix as only argument.
+Its output is searched for email-name pairs using the regular expression given as `abook_regexp`,
+which must include named groups "email" and "name" to match the email address and realname parts
+respectively. See below for an example that uses `abook <http://abook.sourceforge.net/>`_::
+
+    [accounts]
+    [[youraccount]]
+        ...
+        abook_command = abook --mutt-query
+        abook_regexp = '(?P<email>.+?@.+?)\s+(?P<name>.+?)\s*$'
+
+See `here <http://notmuchmail.org/emacstips/#index11h2>`_ for alternative lookup commands. The few others I have tested so far are:
+
+`goobook <http://code.google.com/p/goobook/>`_
+    for cached google contacts lookups::
+
+      abook_command = goobook query
+      abook_regexp = (?P<email>.+?@.+?)\s\s+(?P<name>.+)\s\s+.+
+
+`nottoomuch-addresses <http://www.iki.fi/too/nottoomuch/nottoomuch-addresses/>`_
+    completes contacts found in the notmuch index::
+
+      abook_command = nottoomuch-addresses.sh
+      abook_regexp = \"(?P<name>.+)\"\s*<(?P<email>.*.+?@.+?)>
+
+Don't hesitate to send me your custom `abook_regexp` values to list them here.
+
+
 
 Key Bindings
 ============
 If you want to bind a commandline to a key you can do so by adding the pair to the
-`[MODE-maps]` config section, where MODE is the buffer mode you want the binding to hold.
-Consider the following lines, which allow you to send mails in envelope buffers using the
-combination `control` + `s`::
+`[bindings]` section. This will introduce a *global* binding, that works in
+all modes. To make a binding specific to a mode you have to add the pair
+under the subsection named like the mode. For instance,
+if you want to bind `T` to open a new search for threads tagged with 'todo',
+and be able to toggle this tag in search mode, you'd add this to your config::
 
-    [envelope-maps]
-    ctrl s = send
+    [bindings]
+      T = search tag:todo
 
-Possible MODE strings are:
+      [[search]]
+      t = toggletags todo
+
+.. _modes:
+
+Known modes are:
 
 * envelope
 * search
@@ -67,38 +109,32 @@ Possible MODE strings are:
 * bufferlist
 * global
 
-Bindings defined in section `[global-maps]` are valid in all modes.
-
 Have a look at `the urwid User Input documentation <http://excess.org/urwid/wiki/UserInput>`_ on how key strings are formated.
 
 
-
 Hooks
 =====
-Hooks are python callables that live in a module specified by `hooksfile` in the `[global]`
-section of your config. Per default this points to `~/.config/alot/hooks.py`.
-For every command X in mode M, the callables 'pre_M_X' and 'post_M_X'
--- if defined -- will be called before and after the command is applied respectively.
-
-When a hook gets called, it receives instances of
-
-ui
-  `alot.ui.UI`, the main user interface object that can prompt etc.
-dbm
-  `alot.db.DBManager`, the applications database manager
-aman
-  `alot.account.AccountManager`, can be used to look up account info
-config
-  `alot.settings.config`, a configparser to access the users config
-
-An autogenerated API doc for these can be found at http://alot.rtfd.org ,
-the sphinx sources live in the `docs` folder.
-As an example, consider this pre-hook for the exit command,
-that logs a personalized goodby message::
+Hooks are python callables that live in a module specified by `hooksfile` in the
+config. Per default this points to :file:`~/.config/alot/hooks.py`.
+When a hook gets called it receives a reference to the :class:`main user interface <alot.ui.UI>` and the
+:class:`database manager <alot.db.DBManager>`.
+For every :doc:`COMMAND <../usage/commands>` in mode :ref:`MODE <modes>`, the callables :func:`pre_MODE_COMMAND` and :func:`post_MODE_COMMAND`
+-- if defined -- will be called before and after the command is applied respectively. The signature for the
+pre-`send` hook in envelope mode for example looks like this:
+
+.. py:function:: pre_envelope_send(ui=None, dbm=None)
+
+    :param ui: the main user interface
+    :type ui: :class:`alot.ui.UI`
+    :param dbm: a database manager
+    :type dbm: :class:`alot.db.DBManager`
+
+Consider this pre-hook for the exit command, that logs a personalized goodby message::
 
     import logging
-    def pre_global_exit(aman=None, **rest):
-        accounts = aman.get_accounts()
+    from alot.settings import settings
+    def pre_global_exit(ui, dbm):
+        accounts = settings.get_accounts()
         if accounts:
             logging.info('goodbye, %s!' % accounts[0].realname)
         else:
@@ -106,31 +142,55 @@ that logs a personalized goodby message::
 
 Apart from command pre and posthooks, the following hooks will be interpreted:
 
-`reply_prefix(realname, address, timestamp, **kwargs)`
+.. py:function:: reply_prefix(realname, address, timestamp[, ui= None, dbm=None])
+
     Is used to reformat the first indented line in a reply message.
-    Should return a string and defaults to 'Quoting %s (%s)\n' % (realname, timestamp)
-`forward_prefix(realname, address, timestamp, **kwargs)`
+    This defaults to 'Quoting %s (%s)\n' % (realname, timestamp)' unless this hook is defined
+
+    :param realname: name or the original sender
+    :type realname: str
+    :param address: address of the sender
+    :type address: str
+    :param timestamp: value of the Date header of the replied message
+    :type timestamp: :obj:`datetime.datetime`
+    :rtype: string
+
+.. py:function:: forward_prefix(realname, address, timestamp[, ui= None, dbm=None])
+
     Is used to reformat the first indented line in a inline forwarded message.
-    Returns a string and defaults to 'Forwarded message from %s (%s)\n' % (realname, timestamp)
-`pre_edit_translate(bodytext, **kwargs)`
-    can be used to manipulate a messages bodytext before the editor is called.
-    Receives and returns a string.
-`post_edit_translate(bodytext, **kwargs)`
-    can be used to manipulate a messages bodytext after the editor is called
-    Receives and returns a string.
+    This defaults to 'Forwarded message from %s (%s)\n' % (realname, timestamp)' if this hook is undefined
+
+    :param realname: name or the original sender
+    :type realname: str
+    :param address: address of the sender
+    :type address: str
+    :param timestamp: value of the Date header of the replied message
+    :type timestamp: :obj:`datetime.datetime`
+    :rtype: string
+
+.. py:function:: pre_edit_translate(bodytext[, ui= None, dbm=None])
+
+    used to manipulate a messages bodytext *before* the editor is called.
 
+    :param bodytext: text representation of the mail body as displayed in the ui and as send to the editor
+    :type bodytext: str
+    :rtype: str
+
+.. py:function:: post_edit_translate(bodytext[, ui= None, dbm=None])
+
+    used to manipulate a messages bodytext *after* the editor is called
+
+    :param bodytext: text representation of the mail body as displayed in the ui and as send to the editor
+    :type bodytext: str
+    :rtype: str
     
 
-Widget Colours
-==============
-Alot can be run in 1, 16 or 256 colour mode.
-The requested mode is determined by the commandline parameter `-C` or read from
-option `colourmode` in section `[globals]` of your config file.
-The default is 256, which will be scaled down depending on how many colours
-your terminal supports.
-
-The interface will theme its widgets according to the palette defined in
-section `[MODEc-theme]` where `MODE` is the integer indicating the colour mode.
+Themes
+======
+Alot can be run in 1, 16 or 256 colour mode. The requested mode is determined by the commandline parameter `-C` or read
+from option `colourmode` config value. The default is 256, which scales down depending on how many colours your
+terminal supports.
+
 Have a look at the default config (`alot/defaults/alot.rc`) for a complete list
 of interpreted widget settings; the keys in this section should be self-explanatory.
 
@@ -343,37 +403,3 @@ theme for default themed tags of threads that match the query that maps to the
 Using above proper identifier would distinguish those options as
 ``tag_important_fg`` for the custom theme and ``tag_isimportant_fg`` for the
 highlighting theme.
-
-
-Contacts Completion
-===================
-In each `account` section you can specify a `abook_command` that
-is considered the address book of that account and will be used
-for address completion where appropriate.
-
-This shell command will be called with the search prefix as only argument.
-Its output is searched for email-name pairs using the regular expression given as `abook_regexp`,
-which must include named groups "email" and "name" to match the email address and realname parts
-respectively. See below for an example that uses `abook <http://abook.sourceforge.net/>`_::
-
-    [account YOURACCOUNT]
-    realname = ...
-    address = ...
-    abook_command = abook --mutt-query
-    abook_regexp = '(?P<email>.+?@.+?)\s+(?P<name>.+?)\s*$'
-
-See `here <http://notmuchmail.org/emacstips/#index11h2>`_ for alternative lookup commands. The few others I have tested so far are:
-
-`goobook <http://code.google.com/p/goobook/>`_
-    for cached google contacts lookups::
-
-      abook_command = goobook query
-      abook_regexp = (?P<email>.+?@.+?)\s\s+(?P<name>.+)\s\s+.+
-
-`nottoomuch-addresses <http://www.iki.fi/too/nottoomuch/nottoomuch-addresses/>`_
-    completes contacts found in the notmuch index::
-
-      abook_command = nottoomuch-addresses.sh
-      abook_regexp = \"(?P<name>.+)\"\s*<(?P<email>.*.+?@.+?)>
-
-Don't hesitate to send me your custom `abook_regexp` values to list them here.