doc: info on type/default config values

5 files changed, 194 insertions, 15 deletions

diff --git a/docs/source/configuration/accounts_table.rst b/docs/source/configuration/accounts_table.rst
index 3d55af74..55c5f55d 100644
--- a/docs/source/configuration/accounts_table.rst
+++ b/docs/source/configuration/accounts_table.rst
@@ -5,24 +5,36 @@
 
     your email address
 
+    :type: string
+
 .. _realname:
 
 .. describe:: realname
 
     used to format the (proposed) From-header in outgoing mails
 
+    :type: string
+
 .. _aliases:
 
 .. describe:: aliases
 
     used to clear your addresses/ match account when formatting replies
 
+    :type: string_list
+    :default: ","
+
+
 .. _sendmail-command:
 
 .. describe:: sendmail_command
 
     how to send mails
 
+    :type: string
+    :default: "sendmail"
+
+
 .. _sent-box:
 
 .. describe:: sent_box
@@ -31,12 +43,20 @@
     where to store outgoing mail, e.g. `maildir:///home/you/mail//Sent`
     You can use mbox, maildir, mh, babyl and mmdf in the protocol part of the URL.
 
+    :type: string
+    :default: None
+
+
 .. _sent-tags:
 
 .. describe:: sent_tags
 
     how to tag sent mails.
 
+    :type: string_list
+    :default: "sent,"
+
+
 .. _signature:
 
 .. describe:: signature
@@ -44,6 +64,10 @@
     path to signature file that gets attached to all outgoing mails from this account, optionally
     renamed to `signature_filename`.
 
+    :type: string
+    :default: None
+
+
 .. _signature-as-attachment:
 
 .. describe:: signature_as_attachment
@@ -51,9 +75,17 @@
     attach signature file if set to True, append its content (mimetype text)
     to the body text if set to False. Defaults to False.
 
+    :type: boolean
+    :default: False
+
+
 .. _signature-filename:
 
 .. describe:: signature_filename
 
     signature file's name as it appears in outgoing mails if
     signature_as_attachment is set to True
+
+    :type: string
+    :default: None
+
diff --git a/docs/source/configuration/alotrc_table.rst b/docs/source/configuration/alotrc_table.rst
index 915c1735..fe9f2795 100644
--- a/docs/source/configuration/alotrc_table.rst
+++ b/docs/source/configuration/alotrc_table.rst
@@ -3,7 +3,10 @@
 
 .. describe:: ask_subject
 
-    ask for subject when compose
+
+    :type: boolean
+    :default: True
+
 
 .. _authors-maxlength:
 
@@ -11,24 +14,40 @@
 
     max length of authors line in thread widgets
 
+    :type: integer
+    :default: 30
+
+
 .. _bufferclose-focus-offset:
 
 .. describe:: bufferclose_focus_offset
 
     offset of next focused buffer if the current one gets closed
 
+    :type: integer
+    :default: -1
+
+
 .. _bug-on-exit:
 
 .. describe:: bug_on_exit
 
     confirm exit
 
+    :type: boolean
+    :default: False
+
+
 .. _colourmode:
 
 .. describe:: colourmode
 
     number of colours your terminal supports
 
+    :type: option
+    :default: 256
+
+
 .. _complete-matching-abook-only:
 
 .. describe:: complete_matching_abook_only
@@ -37,24 +56,40 @@
     Set this to True to make tab completion for recipients during compose only
     look in the abook of the account matching the sender address
 
+    :type: boolean
+    :default: False
+
+
 .. _display-content-in-threadline:
 
 .. describe:: display_content_in_threadline
 
     fill threadline with message content
 
+    :type: boolean
+    :default: False
+
+
 .. _displayed-headers:
 
 .. describe:: displayed_headers
 
     headers that get displayed by default
 
+    :type: string_list
+    :default: "From, To, Cc, Bcc, Subject"
+
+
 .. _edit-headers-blacklist:
 
 .. describe:: edit_headers_blacklist
 
     see :ref:`edit_headers_whitelist <edit-headers-whitelist>`
 
+    :type: string_list
+    :default: "Content-Type, MIME-Version, References, In-Reply-To"
+
+
 .. _edit-headers-whitelist:
 
 .. describe:: edit_headers_whitelist
@@ -63,6 +98,10 @@
     used are those that match the whitelist and don't match the blacklist.
     in both cases '*' may be used to indicate all fields.
 
+    :type: string_list
+    :default: "*,"
+
+
 .. _editor-cmd:
 
 .. describe:: editor_cmd
@@ -70,6 +109,10 @@
     editor command
     if unset, alot will first try the EDITOR env variable, then /usr/bin/editor
 
+    :type: string
+    :default: None
+
+
 .. _editor-in-thread:
 
 .. describe:: editor_in_thread
@@ -78,48 +121,80 @@
     In case your editor doesn't run in the same window as alot, setting true here
     will make alot non-blocking during edits
 
+    :type: boolean
+    :default: False
+
+
 .. _editor-spawn:
 
 .. describe:: editor_spawn
 
     use terminal_command to spawn a new terminal for the editor?
 
+    :type: boolean
+    :default: False
+
+
 .. _editor-writes-encoding:
 
 .. describe:: editor_writes_encoding
 
     file encoding used by your editor
 
+    :type: string
+    :default: "UTF-8"
+
+
 .. _envelope-headers-blacklist:
 
 .. describe:: envelope_headers_blacklist
 
     headers that are hidden in envelope buffers by default
 
+    :type: string_list
+    :default: "In-Reply-To, References"
+
+
 .. _flush-retry-timeout:
 
 .. describe:: flush_retry_timeout
 
     timeout in secs after a failed attempt to flush is repeated
 
+    :type: integer
+    :default: 5
+
+
 .. _hooksfile:
 
 .. describe:: hooksfile
 
     where to look up hooks
 
+    :type: string
+    :default: "~/.config/alot/hooks.py"
+
+
 .. _initial-command:
 
 .. describe:: initial_command
 
     initial command when none is given as argument:
 
+    :type: string
+    :default: "search tag:inbox AND NOT tag:killed"
+
+
 .. _notify-timeout:
 
 .. describe:: notify_timeout
 
     time in secs to display status messages
 
+    :type: integer
+    :default: 2
+
+
 .. _print-cmd:
 
 .. describe:: print_cmd
@@ -129,30 +204,50 @@
     threads/messages are piped to this command as plain text.
     muttprint/a2ps works nicely
 
+    :type: string
+    :default: None
+
+
 .. _quit-on-last-bclose:
 
 .. describe:: quit_on_last_bclose
 
     shut down when the last buffer gets closed
 
+    :type: boolean
+    :default: False
+
+
 .. _search-threads-sort-order:
 
 .. describe:: search_threads_sort_order
 
     default sort order of results in a search
 
+    :type: option
+    :default: newest_first
+
+
 .. _show-statusbar:
 
 .. describe:: show_statusbar
 
     display status-line?
 
+    :type: boolean
+    :default: True
+
+
 .. _tabwidth:
 
 .. describe:: tabwidth
 
     number of spaces used to replace tab characters
 
+    :type: integer
+    :default: 8
+
+
 .. _template-dir:
 
 .. describe:: template_dir
@@ -160,24 +255,40 @@
     templates directory that contains your message templates.
     It will be used if you give `compose --template` a filename without a path prefix.
 
+    :type: string
+    :default: "$XDG_CONFIG_HOME/alot/templates"
+
+
 .. _terminal-cmd:
 
 .. describe:: terminal_cmd
 
     set terminal command used for spawning shell commands
 
+    :type: string
+    :default: "x-terminal-emulator -e"
+
+
 .. _theme:
 
 .. describe:: theme
 
     name of the theme to use
 
+    :type: string
+    :default: None
+
+
 .. _themes-dir:
 
 .. describe:: themes_dir
 
     directory containing theme files
 
+    :type: string
+    :default: None
+
+
 .. _thread-authors-me:
 
 .. describe:: thread_authors_me
@@ -185,6 +296,10 @@
     Word to replace own addresses with. Works in combination with
     :ref:`thread_authors_replace_me <thread-authors-replace-me>`
 
+    :type: string
+    :default: "Me"
+
+
 .. _thread-authors-replace-me:
 
 .. describe:: thread_authors_replace_me
@@ -192,12 +307,19 @@
     Replace own email addresses with "me" in author lists
     Uses own addresses and aliases in all configured accounts.
 
+    :type: boolean
+    :default: True
+
+
 .. _timestamp-format:
 
 .. describe:: timestamp_format
 
-    timestamp format in strftime format syntax:
-    http://docs.python.org/library/datetime.html#strftime-strptime-behavior
+    timestamp format in `strftime format syntax <http://docs.python.org/library/datetime.html#strftime-strptime-behavior>`_
+
+    :type: string
+    :default: None
+
 
 .. _user-agent:
 
@@ -206,3 +328,7 @@
     value of the User-Agent header used for outgoing mails.
     setting this to the empty string will cause alot to omit the header all together.
     The string '{version}' will be replaced by the version string of the running instance.
+
+    :type: string
+    :default: "alot/{version}"
+
diff --git a/docs/source/generate_configs.py b/docs/source/generate_configs.py
index 96eb37c1..41fa9a08 100755
--- a/docs/source/generate_configs.py
+++ b/docs/source/generate_configs.py
@@ -4,29 +4,51 @@ HERE = os.path.dirname(__file__)
 sys.path.append(os.path.join(HERE, '..', '..', '..'))
 from alot.commands import COMMANDS
 from configobj import ConfigObj
+from validate import Validator
 import re
 
-def rewrite_scalarcomments(config, path, sort=False):
+def rewrite_entries(config, path, sec=None, sort=False):
     file = open(path, 'w')
+
+    if sec == None:
+        sec = config
     if sort:
-        config.scalars.sort()
-    for entry in config.scalars:
+        sec.scalars.sort()
+    for entry in sec.scalars:
+        v = Validator()
+        #config.validate(v)
+        #print config[entry]
+        #etype = re.sub('\(.*\)','', config[entry])
+        ##if etype == 'option':
+        etype, eargs, ekwargs, default = v._parse_check(sec[entry])
+        if default is not None:
+            default = config._quote(default)
+
+        #print etype
         description = '\n.. _%s:\n' % entry.replace('_', '-')
         description += '\n.. describe:: %s\n\n' % entry
-        comments = [config.inline_comments[entry]] + config.comments[entry]
+        comments = [sec.inline_comments[entry]] + sec.comments[entry]
         for c in comments:
             if c:
                 description += ' '*4 + re.sub('^\s*#\s*', '', c) + '\n'
+        description += '\n    :type: %s\n' % etype
+
+        if default != None:
+            if etype in ['string', 'string_list'] and default != 'None':
+                description += '    :default: "%s"\n\n' % (default)
+            else:
+                description += '    :default: %s\n\n' % (default)
         file.write(description)
     file.close()
 
 if __name__ == "__main__":
     specpath = os.path.join(HERE, '..','..', 'alot', 'defaults', 'alot.rc.spec')
-    config = ConfigObj(specpath)
+    config = ConfigObj(None, configspec=specpath, stringify=False, list_values=False)
+    config.validate(Validator())
 
     alotrc_table_file = os.path.join(HERE, 'configuration', 'alotrc_table.rst')
-    rewrite_scalarcomments(config, alotrc_table_file, sort=True)
+    rewrite_entries(config.configspec, alotrc_table_file, sort=True)
 
-    rewrite_scalarcomments(config['accounts']['__many__'],
-                           os.path.join(HERE, 'configuration',
-                                        'accounts_table.rst'))
+    rewrite_entries(config, os.path.join(HERE, 'configuration',
+                                         'accounts_table.rst'),
+                    sec=config.configspec['accounts']['__many__'])
diff --git a/docs/source/index.rst b/docs/source/index.rst
index ef0368dc..47dacf3e 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -11,7 +11,7 @@ User Manual
    :maxdepth: 2
    :numbered:
    
-   installation/index
+   installation
    usage/index
    configuration/index
    api/index
diff --git a/docs/source/installation/index.rst b/docs/source/installation.rst
index 0dba1f15..39f2ce81 100644
--- a/docs/source/installation/index.rst
+++ b/docs/source/installation.rst
@@ -1,6 +1,5 @@
-*****
 Installation
-*****
+************
 
 Dependencies
 =======