Merge pull request #914 from lucc/docs2

Some more fixes for building docs

12 files changed, 121 insertions, 44 deletions

diff --git a/alot/commands/globals.py b/alot/commands/globals.py
index 49906513..d3dddf61 100644
--- a/alot/commands/globals.py
+++ b/alot/commands/globals.py
@@ -351,7 +351,7 @@ class RepeatCommand(Command):
     (['command'], {'help': 'python command string to call'})])
 class CallCommand(Command):
 
-    """ Executes python code """
+    """Executes python code"""
     repeatable = True
 
     def __init__(self, command, **kwargs):
@@ -563,10 +563,8 @@ class FlushCommand(Command):
     (['commandname'], {'help': 'command or \'bindings\''})])
 class HelpCommand(Command):
 
-    """
-    display help for a command. Use \'bindings\' to
-    display all keybings interpreted in current mode.'
-    """
+    """display help for a command. Use \'bindings\' to display all keybings
+    interpreted in current mode.'"""
     def __init__(self, commandname='', **kwargs):
         """
         :param commandname: command to document
diff --git a/alot/commands/search.py b/alot/commands/search.py
index b79ce831..b8ecef6d 100644
--- a/alot/commands/search.py
+++ b/alot/commands/search.py
@@ -145,8 +145,7 @@ class RetagPromptCommand(Command):
     help="""flip presence of tags on this thread.
     A tag is considered present if at least one message contained in this
     thread is tagged with it. In that case this command will remove the tag
-    from every message in the thread.
-    """)
+    from every message in the thread.""")
 class TagCommand(Command):
 
     """manipulate message tags"""
diff --git a/docs/Makefile b/docs/Makefile
index 68f7e497..e8d0c73f 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -52,6 +52,9 @@ $(CONFIG_OPTION_TABLES): ../alot/defaults/alot.rc.spec
 clean:
 	-$(RM) -rf $(BUILDDIR)/*
 
+cleanall: clean
+	-$(RM) -rf $(CONFIG_OPTION_TABLES) $(COMMAND_OPTION_TABLES)
+
 html: $(CONFIG_OPTION_TABLES) $(COMMAND_OPTION_TABLES)
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
diff --git a/docs/source/configuration/accounts_table b/docs/source/configuration/accounts_table
index cc3e5646..265bc34b 100644
--- a/docs/source/configuration/accounts_table
+++ b/docs/source/configuration/accounts_table
@@ -31,6 +31,16 @@
     :default: ,
 
 
+.. _alias-regexp:
+
+.. describe:: alias_regexp
+
+     a regex for catching further aliases (like + extensions).
+
+    :type: string
+    :default: None
+
+
 .. _sendmail-command:
 
 .. describe:: sendmail_command
@@ -127,10 +137,26 @@
 
 .. describe:: encrypt_by_default
 
-     Outgoing messages will be GPG encrypted by default if this is set to True.
-
-    :type: boolean
-    :default: False
+     Alot will try to GPG encrypt outgoing messages by default when this
+     is set to `all` or `trusted`.  If set to `all` the message will be
+     encrypted for all recipients for who a key is available in the key
+     ring.  If set to `trusted` it will be encrypted to all
+     recipients if a trusted key is available for all recipients (one
+     where the user id for the key is signed with a trusted signature).
+
+     .. note:: If the message will not be encrypted by default you can
+               still use the :ref:`toggleencrypt
+               <cmd.envelope.toggleencrypt>`, :ref:`encrypt
+               <cmd.envelope.encrypt>` and :ref:`unencrypt
+               <cmd.envelope.unencrypt>` commands to encrypt it.
+     .. note:: The values `True` and `False` are interpreted as `all` and
+               `none` respectively.  They are kept for backwards
+               compatibility to give users a change to migrate to the new
+               option type.  They might become deprecated in future
+               versions.
+
+    :type: option, one of ['all', 'none', 'trusted', 'True', 'False', 'true', 'false', 'Yes', 'No', 'yes', 'no', '1', '0']
+    :default: none
 
 
 .. _gpg-key:
diff --git a/docs/source/configuration/alotrc_table b/docs/source/configuration/alotrc_table
index e1a4fa73..ef0c7eaa 100644
--- a/docs/source/configuration/alotrc_table
+++ b/docs/source/configuration/alotrc_table
@@ -34,6 +34,16 @@
     :default: True
 
 
+.. _auto-replyto-mailinglist:
+
+.. describe:: auto_replyto_mailinglist
+
+     Automatically switch to list reply mode if appropriate
+
+    :type: boolean
+    :default: False
+
+
 .. _bounce-force-address:
 
 .. describe:: bounce_force_address
@@ -56,16 +66,6 @@
     :default: True
 
 
-.. _auto_replyto_mailinglist:
-
-.. describe:: auto_replyto_mailinglist
-
-     Automatically switch to list reply mode if appropriate
-
-    :type: boolean
-    :default: False
-
-
 .. _bufferclose-focus-offset:
 
 .. describe:: bufferclose_focus_offset
@@ -192,7 +192,7 @@
 
 .. describe:: editor_spawn
 
-     use terminal_cmd to spawn a new terminal for the editor?
+     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
@@ -238,7 +238,8 @@
 
 .. describe:: flush_retry_timeout
 
-     timeout in seconds after a failed attempt to writeout the database is repeated
+     timeout in seconds after a failed attempt to writeout the database is
+     repeated. Set to 0 for no retry.
 
     :type: integer
     :default: 5
@@ -340,6 +341,17 @@
     :default: ,
 
 
+.. _msg-summary-hides-threadwide-tags:
+
+.. describe:: msg_summary_hides_threadwide_tags
+
+     In a thread buffer, hide from messages summaries tags that are commom to all
+     messages in that thread.
+
+    :type: boolean
+    :default: True
+
+
 .. _notify-timeout:
 
 .. describe:: notify_timeout
@@ -403,6 +415,19 @@
     :default: "> "
 
 
+.. _reply-account-header-priority:
+
+.. describe:: reply_account_header_priority
+
+     The list of headers to match to determine sending account for a reply.
+     Headers are searched in the order in which they are specified here, and the first header
+     containing a match is used. If multiple accounts match in that header, the one defined
+     first in the account block is used.
+
+    :type: string list
+    :default: From, To, Cc, Envelope-To, X-Envelope-To, Delivered-To
+
+
 .. _reply-force-address:
 
 .. describe:: reply_force_address
@@ -548,6 +573,17 @@
     :default: "Me"
 
 
+.. _thread-authors-order-by:
+
+.. describe:: thread_authors_order_by
+
+     When constructing the unique list of thread authors, order by date of
+     author's first or latest message in thread
+
+    :type: option, one of ['first_message', 'latest_message']
+    :default: first_message
+
+
 .. _thread-authors-replace-me:
 
 .. describe:: thread_authors_replace_me
@@ -559,17 +595,6 @@
     :default: True
 
 
-.. _thread-authors-order-by:
-
-.. describe:: thread_authors_order_by
-
-    In which order to list authors. By default, list authors in the order they
-    joined the conversation.
-
-    :type: option, one of ['first_message', 'latest_message']
-    :default: first_message
-
-
 .. _thread-statusbar:
 
 .. describe:: thread_statusbar
@@ -588,6 +613,22 @@
     :default: [{buffer_no}: thread] {subject}, {input_queue} total messages: {total_messages}
 
 
+.. _thread-subject:
+
+.. describe:: thread_subject
+
+     What should be considered to be "the thread subject".
+     Valid values are:
+
+     * 'notmuch' (the default), will use the thread subject from notmuch, which
+       depends on the selected sorting method
+     * 'oldest' will always use the subject of the oldest message in the thread as
+       the thread subject
+
+    :type: option, one of ['oldest', 'notmuch']
+    :default: notmuch
+
+
 .. _timestamp-format:
 
 .. describe:: timestamp_format
diff --git a/docs/source/generate_commands.py b/docs/source/generate_commands.py
index e31c130c..0fd1fb01 100755
--- a/docs/source/generate_commands.py
+++ b/docs/source/generate_commands.py
@@ -1,7 +1,7 @@
 import sys
 import os
 HERE = os.path.dirname(__file__)
-sys.path.append(os.path.join(HERE, '..', '..', '..'))
+sys.path.insert(0, os.path.join(HERE, '..', '..'))
 from alot.commands import *
 from alot.commands import COMMANDS
 import alot.buffers
diff --git a/docs/source/generate_configs.py b/docs/source/generate_configs.py
index 4320e7f3..b79f3f69 100755
--- a/docs/source/generate_configs.py
+++ b/docs/source/generate_configs.py
@@ -1,7 +1,7 @@
 import sys
 import os
 HERE = os.path.dirname(__file__)
-sys.path.append(os.path.join(HERE, '..', '..', '..'))
+sys.path.insert(0, os.path.join(HERE, '..', '..'))
 from alot.commands import COMMANDS
 from configobj import ConfigObj
 from validate import Validator
@@ -38,7 +38,8 @@ def rewrite_entries(config, path, specpath, sec=None, sort=False):
         comments = [sec.inline_comments[entry]] + sec.comments[entry]
         for c in comments:
             if c:
-                description += ' '*4 + re.sub('^\s*#', '', c) + '\n'
+                description += ' '*4 + re.sub('^\s*#', '', c)
+                description = description.rstrip(' ') + '\n'
         if etype == 'option':
             description += '\n    :type: option, one of %s\n' % eargs
         else:
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
index 5b008b48..2110315b 100644
--- a/docs/source/installation.rst
+++ b/docs/source/installation.rst
@@ -51,8 +51,7 @@ Don't have pip installed? Just download and extract, then run::
   python setup.py install --user
 
 Make sure :file:`~/.local/bin` is in your :envvar:`PATH`. For system-wide
-installation omit the :option:`--user` flag and call with the respective
-permissions.
+installation omit the `--user` flag and call with the respective permissions.
 
 .. rubric:: generate manual and manpage
 
diff --git a/docs/source/usage/modes/envelope.rst b/docs/source/usage/modes/envelope.rst
index 7fdb6c4b..896bc7d0 100644
--- a/docs/source/usage/modes/envelope.rst
+++ b/docs/source/usage/modes/envelope.rst
@@ -35,6 +35,8 @@ The following commands are available in envelope mode
     argument
         keyid of the key to encrypt with
 
+    optional arguments
+        :---trusted: only add trusted keys.
 
 .. _cmd.envelope.togglesign:
 
@@ -129,6 +131,8 @@ The following commands are available in envelope mode
     argument
         keyid of the key to encrypt with
 
+    optional arguments
+        :---trusted: only add trusted keys.
 
 .. _cmd.envelope.save:
 
diff --git a/docs/source/usage/modes/global.rst b/docs/source/usage/modes/global.rst
index 90d61f35..74514910 100644
--- a/docs/source/usage/modes/global.rst
+++ b/docs/source/usage/modes/global.rst
@@ -55,8 +55,8 @@ The following commands are available globally
 
 .. describe:: help
 
-    display help for a command. Use 'bindings' to
-    display all keybings interpreted in current mode.'
+    display help for a command. Use 'bindings' to display all keybings
+    interpreted in current mode.'
 
     argument
         command or 'bindings'
@@ -116,6 +116,9 @@ The following commands are available globally
 
     compose a new email
 
+    argument
+        None
+
     optional arguments
         :---sender: sender.
         :---template: path to a template message file.
@@ -171,4 +174,6 @@ The following commands are available globally
 
     opens taglist buffer
 
+    optional arguments
+        :---tags: tags to display.
 
diff --git a/docs/source/usage/modes/search.rst b/docs/source/usage/modes/search.rst
index 20e22b44..51143093 100644
--- a/docs/source/usage/modes/search.rst
+++ b/docs/source/usage/modes/search.rst
@@ -19,7 +19,7 @@ The following commands are available in search mode
 
 .. describe:: untag
 
-    remove tags from all messages in the thread
+    remove tags from all messages in the thread that match the query
 
     argument
         comma separated list of tags
@@ -42,7 +42,7 @@ The following commands are available in search mode
 
 .. describe:: retag
 
-    set tags of all messages in the thread
+    set tags of all messages in the thread that match the current query
 
     argument
         comma separated list of tags
@@ -62,7 +62,7 @@ The following commands are available in search mode
 
 .. describe:: tag
 
-    add tags to all messages in the thread
+    add tags to all messages in the thread that match the current query
 
     argument
         comma separated list of tags
diff --git a/docs/source/usage/modes/thread.rst b/docs/source/usage/modes/thread.rst
index 1db63f61..5daf92ca 100644
--- a/docs/source/usage/modes/thread.rst
+++ b/docs/source/usage/modes/thread.rst
@@ -22,6 +22,7 @@ The following commands are available in thread mode
         :---add_tags: add 'Tags' header to the message.
         :---shell: let the shell interpret the command.
         :---notify_stdout: display cmd's stdout as notification.
+        :---field_key: mailcap field key for decoding (Defaults to: 'copiousoutput').
 
 .. _cmd.thread.editnew: