docstrings for new settings methods

6 files changed, 675 insertions, 0 deletions

diff --git a/docs/source/configuration/accounts_table b/docs/source/configuration/accounts_table
new file mode 100644
index 00000000..aea1956c
--- /dev/null
+++ b/docs/source/configuration/accounts_table
@@ -0,0 +1,135 @@
+
+.. CAUTION: THIS FILE IS AUTO-GENERATED
+    from the inline comments of specfile defaults/alot.rc.spec.
+
+    If you want to change its content make your changes
+    to that spec to ensure they woun't be overwritten later.
+
+.. _address:
+
+.. describe:: address
+
+     your main 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
+
+     sendmail command. This is the shell command used to send out mails via the sendmail protocol
+
+    :type: string
+    :default: "sendmail -t"
+
+
+.. _sent-box:
+
+.. describe:: sent_box
+
+     where to store outgoing mails, e.g. `maildir:///home/you/mail/Sent`.
+     You can use mbox, maildir, mh, babyl and mmdf in the protocol part of the URL.
+    
+     .. note:: If you want to add outgoing mails automatically to the notmuch index
+               you must use maildir in a path within your notmuch database path.
+
+    :type: mail_container
+    :default: None
+
+
+.. _draft-box:
+
+.. describe:: draft_box
+
+     where to store draft mails, e.g. `maildir:///home/you/mail/Drafts`.
+     You can use mbox, maildir, mh, babyl and mmdf in the protocol part of the URL.
+    
+     .. note:: You will most likely want drafts indexed by notmuch to be able to
+               later access them within alot. This currently only works for
+               maildir containers in a path below your notmuch database path.
+
+    :type: mail_container
+    :default: None
+
+
+.. _sent-tags:
+
+.. describe:: sent_tags
+
+     list of tags to automatically add to outgoing messages
+
+    :type: string list
+    :default: sent,
+
+
+.. _signature:
+
+.. describe:: signature
+
+     path to signature file that gets attached to all outgoing mails from this account, optionally
+     renamed to ref:`signature_filename <signature-filename>`.
+
+    :type: string
+    :default: None
+
+
+.. _signature-as-attachment:
+
+.. describe:: signature_as_attachment
+
+     attach signature file if set to True, append its content (mimetype text)
+     to the body text if set to False.
+
+    :type: boolean
+    :default: False
+
+
+.. _signature-filename:
+
+.. describe:: signature_filename
+
+     signature file's name as it appears in outgoing mails if
+     :ref:`signature_as_attachment <signature-as-attachment>` is set to True
+
+    :type: string
+    :default: None
+
+
+.. _sign-by-default:
+
+.. describe:: sign_by_default
+
+     Outgoing messages will be GPG signed by default if this is set to True.
+
+    :type: boolean
+    :default: False
+
+
+.. _gpg-key:
+
+.. describe:: gpg_key
+
+     The GPG key ID you want to use with this account. If unset, alot will
+     use your default key.
+
+    :type: string
+    :default: None
+
diff --git a/docs/source/configuration/alotrc_table b/docs/source/configuration/alotrc_table
new file mode 100644
index 00000000..6b4e2092
--- /dev/null
+++ b/docs/source/configuration/alotrc_table
@@ -0,0 +1,471 @@
+
+.. CAUTION: THIS FILE IS AUTO-GENERATED
+    from the inline comments of specfile defaults/alot.rc.spec.
+
+    If you want to change its content make your changes
+    to that spec to ensure they woun't be overwritten later.
+
+.. _ask-subject:
+
+.. describe:: ask_subject
+
+
+    :type: boolean
+    :default: True
+
+
+.. _attachment-prefix:
+
+.. describe:: attachment_prefix
+
+     directory prefix for downloading attachments
+
+    :type: string
+    :default: "~"
+
+
+.. _authors-maxlength:
+
+.. describe:: authors_maxlength
+
+     maximal length of authors string in search mode before it gets truncated
+
+    :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
+
+
+.. _bufferlist-statusbar:
+
+.. describe:: bufferlist_statusbar
+
+     Format of the status-bar in bufferlist mode.
+     This is a pair of strings to be left and right aligned in the status-bar that may contain variables:
+    
+     * `{buffer_no}`: index of this buffer in the global buffer list
+     * `{total_messages}`: total numer of messages indexed by notmuch
+     * `{pending_writes}`: number of pending write operations to the index
+
+    :type: mixed_list
+    :default: [{buffer_no}: bufferlist], total messages: {total_messages}
+
+
+.. _bug-on-exit:
+
+.. describe:: bug_on_exit
+
+     confirm exit
+
+    :type: boolean
+    :default: False
+
+
+.. _colourmode:
+
+.. describe:: colourmode
+
+     number of colours to use
+
+    :type: option, one of ['1', '16', '256']
+    :default: 256
+
+
+.. _complete-matching-abook-only:
+
+.. describe:: complete_matching_abook_only
+
+     in case more than one account has an address book:
+     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
+
+     Which header fields should be editable in your editor
+     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
+
+     editor command
+     if unset, alot will first try the :envvar:`EDITOR` env variable, then :file:`/usr/bin/editor`
+
+    :type: string
+    :default: None
+
+
+.. _editor-in-thread:
+
+.. describe:: editor_in_thread
+
+     call editor in separate thread.
+     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?
+     equivalent to always providing the `--spawn=yes` parameter to compose/edit commands
+
+    :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
+
+
+.. _envelope-statusbar:
+
+.. describe:: envelope_statusbar
+
+     Format of the status-bar in envelope mode.
+     This is a pair of strings to be left and right aligned in the status-bar.
+     Apart from the global variables listed at :ref:`bufferlist_statusbar <bufferlist-statusbar>`
+     these strings may contain variables:
+    
+     * `{to}`: To-header of the envelope
+
+    :type: mixed_list
+    :default: [{buffer_no}: envelope], total messages: {total_messages}
+
+
+.. _flush-retry-timeout:
+
+.. describe:: flush_retry_timeout
+
+     timeout in seconds after a failed attempt to writeout the database is repeated
+
+    :type: integer
+    :default: 5
+
+
+.. _forward-subject-prefix:
+
+.. describe:: forward_subject_prefix
+
+     String prepended to subject header on forward
+     only if original subject doesn't start with 'Fwd:' or this prefix
+
+    :type: string
+    :default: "Fwd: "
+
+
+.. _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
+
+     how to print messages:
+     this specifies a shell command used for printing.
+     threads/messages are piped to this command as plain text.
+     muttprint/a2ps works nicely
+
+    :type: string
+    :default: None
+
+
+.. _prompt-suffix:
+
+.. describe:: prompt_suffix
+
+     Suffix of the prompt used when waiting for user input
+
+    :type: string
+    :default: ":"
+
+
+.. _quit-on-last-bclose:
+
+.. describe:: quit_on_last_bclose
+
+     shut down when the last buffer gets closed
+
+    :type: boolean
+    :default: False
+
+
+.. _quote-prefix:
+
+.. describe:: quote_prefix
+
+     String prepended to line when quoting
+
+    :type: string
+    :default: "> "
+
+
+.. _reply-subject-prefix:
+
+.. describe:: reply_subject_prefix
+
+     String prepended to subject header on reply
+     only if original subject doesn't start with 'Re:' or this prefix
+
+    :type: string
+    :default: "Re: "
+
+
+.. _search-statusbar:
+
+.. describe:: search_statusbar
+
+     Format of the status-bar in search mode.
+     This is a pair of strings to be left and right aligned in the status-bar.
+     Apart from the global variables listed at :ref:`bufferlist_statusbar <bufferlist-statusbar>`
+     these strings may contain variables:
+    
+     * `{querystring}`: search string
+     * `{result_count}`: number of matching messages
+     * `{result_count_positive}`: 's' if result count is greater than 0.
+
+    :type: mixed_list
+    :default: [{buffer_no}: search] for "{querystring}", {result_count} of {total_messages} messages
+
+
+.. _search-threads-sort-order:
+
+.. describe:: search_threads_sort_order
+
+     default sort order of results in a search
+
+    :type: option, one of ['oldest_first', 'newest_first', 'message_id', 'unsorted']
+    :default: newest_first
+
+
+.. _show-statusbar:
+
+.. describe:: show_statusbar
+
+     display status-bar at the bottom of the screen?
+
+    :type: boolean
+    :default: True
+
+
+.. _tabwidth:
+
+.. describe:: tabwidth
+
+     number of spaces used to replace tab characters
+
+    :type: integer
+    :default: 8
+
+
+.. _taglist-statusbar:
+
+.. describe:: taglist_statusbar
+
+     Format of the status-bar in taglist mode.
+     This is a pair of strings to be left and right aligned in the status-bar.
+     These strings may contain variables listed at :ref:`bufferlist_statusbar <bufferlist-statusbar>`
+     that will be substituted accordingly.
+
+    :type: mixed_list
+    :default: [{buffer_no}: taglist], total messages: {total_messages}
+
+
+.. _template-dir:
+
+.. describe:: template_dir
+
+     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
+
+     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
+
+     Replace own email addresses with "me" in author lists
+     Uses own addresses and aliases in all configured accounts.
+
+    :type: boolean
+    :default: True
+
+
+.. _thread-statusbar:
+
+.. describe:: thread_statusbar
+
+     Format of the status-bar in thread mode.
+     This is a pair of strings to be left and right aligned in the status-bar.
+     Apart from the global variables listed at :ref:`bufferlist_statusbar <bufferlist-statusbar>`
+     these strings may contain variables:
+    
+     * `{tid}`: thread id
+     * `{subject}`: subject line of the thread
+     * `{authors}`: abbreviated authors string for this thread
+     * `{message_count}`: number of contained messages
+
+    :type: mixed_list
+    :default: [{buffer_no}: thread] {subject}, total messages: {total_messages}
+
+
+.. _timestamp-format:
+
+.. describe:: timestamp_format
+
+     timestamp format in `strftime format syntax <http://docs.python.org/library/datetime.html#strftime-strptime-behavior>`_
+
+    :type: string
+    :default: None
+
+
+.. _user-agent:
+
+.. describe:: user_agent
+
+     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/description b/docs/source/description
new file mode 100644
index 00000000..9dea9693
--- /dev/null
+++ b/docs/source/description
@@ -0,0 +1,4 @@
+Alot is a terminal-based mail user agent for the notmuch mail system.
+It features a modular and command prompt driven interface
+to provide a full MUA experience as an alternative to the Emacs mode shipped
+with notmuch.
diff --git a/docs/source/usage/commands b/docs/source/usage/commands
new file mode 100644
index 00000000..ec0be2eb
--- /dev/null
+++ b/docs/source/usage/commands
@@ -0,0 +1,29 @@
+.. _commands:
+
+Commands
+========
+
+:doc:`modes/global`
+    globally available commands
+:doc:`modes/search`
+    shows a result list of threads for a query
+:doc:`modes/thread`
+    displays a thread as a tree of messages
+:doc:`modes/envelope`
+    message composition mode
+:doc:`modes/bufferlist`
+    lists all active buffers
+:doc:`modes/taglist`
+    lists all tagstrings present in the notmuch database
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   modes/global
+   modes/search
+   modes/thread
+   modes/envelope
+   modes/bufferlist
+   modes/taglist
+
diff --git a/docs/source/usage/first_steps b/docs/source/usage/first_steps
new file mode 100644
index 00000000..e99c44ce
--- /dev/null
+++ b/docs/source/usage/first_steps
@@ -0,0 +1,10 @@
+The arrow keys, `page-up/down`, `j`, `k` and `Space` can be used to move the focus.
+`Escape` cancels prompts and `Enter` selects. Hit `:` at any time and type in commands
+to the prompt.
+
+The interface shows one buffer at a time, you can use `tab` and `Shift-Tab` to switch
+between them, close the current buffer with `d` and list them all with `;`.
+
+The buffer type or *mode* (displayed at the bottom left) determines which prompt commands
+are available. Usage information on any command can be listed by typing `help YOURCOMMAND`
+to the prompt; The key bindings for the current mode are listed upon pressing `?`.
diff --git a/docs/source/usage/synopsis b/docs/source/usage/synopsis
new file mode 100644
index 00000000..5bfb8e88
--- /dev/null
+++ b/docs/source/usage/synopsis
@@ -0,0 +1,26 @@
+.. code-block:: none
+
+    alot [-r] [-c CONFIGFILE] [-n NOTMUCHCONFIGFILE] [-C {1,16,256}] [-p DB_PATH]
+         [-d {debug,info,warning,error}] [-l LOGFILE] [--version] [--help]
+         [command]
+
+Options
+
+    -r, --read-only                open db in read only mode
+    -c, --config=FILENAME          config file (default: ~/.config/alot/config)
+    -n, --notmuch-config=FILENAME  notmuch config (default: $NOTMUCH_CONFIG or ~/.notmuch-config)
+    -C, --colour-mode=COLOUR        terminal colour mode (default: 256). Must be 1, 16 or 256
+    -p, --mailindex-path=PATH      path to notmuch index
+    -d, --debug-level=LEVEL        debug log (default: info). Must be one of debug,info,warning or error
+    -l, --logfile=FILENAME         logfile (default: /dev/null)
+    --version                      Display version string and exit
+    --help                         Display  help and exit
+
+
+Commands
+
+    search
+        start in a search buffer using the querystring provided as
+        parameter. See the SEARCH SYNTAX section of notmuch(1).
+    compose
+        compose a new message