usage docs

are now better structured and more importantly,
the generated sections per command will show up in the index,
which lets us access their urls easily for in-app documentation.

3 files changed, 43 insertions, 570 deletions

diff --git a/docs/user/source/generate_commands.py b/docs/user/source/generate_commands.py
index f0c5f935..9179b952 100644..100755
--- a/docs/user/source/generate_commands.py
+++ b/docs/user/source/generate_commands.py
@@ -1,8 +1,10 @@
 import sys
 import os
-sys.path.append(os.path.join(os.path.dirname(__file__), '..', '..', '..'))
+HERE = os.path.dirname(__file__)
+sys.path.append(os.path.join(HERE, '..', '..', '..'))
 from alot.commands import *
 from alot.commands import COMMANDS
+import alot.buffers
 from argparse import HelpFormatter, SUPPRESS, OPTIONAL, ZERO_OR_MORE, ONE_OR_MORE, PARSER, REMAINDER
 from gettext import gettext as _
 import collections as _collections
@@ -50,6 +52,7 @@ def rstify_parser(parser):
         usage = usage.replace('--','---')
 
         # section header
+        out += '.. index:: %s\n' % parser.prog
         out +='\n%s\n' % parser.prog
         out += '_'*len(parser.prog)
         out += '\n\n'
@@ -98,9 +101,43 @@ def rstify_parser(parser):
 
         return out
 
-for mode, modecommands in COMMANDS.items():
-    print mode + '-mode\n' + '-' * (len(mode) + 5)
-    for cmdstring,struct in modecommands.items():
-        cls, parser, forced_args = struct
-        print rstify_parser(parser)
+def get_mode_docs():
+    docs = {}
+    b = alot.buffers.Buffer
+    for entry in alot.buffers.__dict__.values():
+        if isinstance(entry, type):
+            if issubclass(entry, b) and not entry == b:
+                docs[entry.modename] = entry.__doc__.strip()
+    return docs
 
+
+if __name__ == "__main__":
+
+    modes = []
+    for mode, modecommands in COMMANDS.items():
+        modefilename = mode+'.rst'
+        modefile = open(os.path.join(HERE, 'usage', 'modes', modefilename), 'w')
+        modefile.write('%s\n%s\n' % (mode, '-' * len(mode)))
+        if mode != 'global':
+            modes.append(mode)
+            modefile.write('The following commands are available in %s mode\n\n' % mode)
+        else:
+            modefile.write('The following commands are available globally\n\n')
+        for cmdstring,struct in modecommands.items():
+            cls, parser, forced_args = struct
+            modefile.write(rstify_parser(parser))
+        modefile.close()
+    indexfile = open(os.path.join(HERE, 'usage', 'commands.rst'), 'w')
+
+    mode_docstrings = get_mode_docs()
+    tbl = ':doc:`modes/global`\n'
+    tbl += (' ' * 4) + 'globally available commands\n'
+    for m in modes:
+        tbl += ':doc:`modes/%s`\n' % m
+        tbl += (' ' * 4) + mode_docstrings[m] + '\n'
+
+    includes = '\n'.join([':doc:`modes/%s`' % m for m in modes])
+    indexfile.write('Commands\n========\n\n')
+    indexfile.write('\n\n')
+    indexfile.write(tbl)
+    indexfile.close()
diff --git a/docs/user/source/usage/commands.rst b/docs/user/source/usage/commands.rst
deleted file mode 100644
index 799176b9..00000000
--- a/docs/user/source/usage/commands.rst
+++ /dev/null
@@ -1,561 +0,0 @@
-search-mode
------------
-
-sort
-____
-
-set sort order
-
-argument
-	sort order. valid choices are: \`oldest_first\`,\`newest_first\`,\`message_id\`,\`unsorted\`.
-
-
-
-
-untag
-_____
-
-remove tags from all messages in the thread
-
-argument
-	comma separated list of tags
-
-
-
-
-retag
-_____
-
-set tags of all messages in the thread
-
-argument
-	comma separated list of tags
-
-
-
-
-refineprompt
-____________
-
-prompt to change this buffers querystring
-
-
-
-
-tag
-___
-
-add tags to all messages in the thread
-
-argument
-	comma separated list of tags
-
-
-
-
-refine
-______
-
-refine query
-
-argument
-	search string
-
-optional arguments
-	:---sort: sort order. Valid choices are: \`oldest_first\`,\`newest_first\`,\`message_id\`,\`unsorted\`.
-
-
-
-retagprompt
-___________
-
-prompt to retag selected threads' tags
-
-
-
-
-toggletags
-__________
-
-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.
-    
-
-argument
-	comma separated list of tags
-
-
-
-
-select
-______
-
-open thread in a new buffer
-
-
-
-thread-mode
------------
-
-pipeto
-______
-
-pipe message(s) to stdin of a shellcommand
-
-argument
-	shellcommand to pipe to
-
-optional arguments
-	:---all: pass all messages.
-	:---format: output format. Valid choices are: \`raw\`,\`decoded\`,\`id\`,\`filepath\` (Defaults to: 'raw').
-	:---separately: call command once for each message.
-	:---background: disable stdin and ignore stdout.
-
-
-
-editnew
-_______
-
-edit message in as new
-
-
-
-
-toggleheaders
-_____________
-
-display all headers
-
-optional arguments
-	:---all: affect all messages.
-
-
-
-print
-_____
-
-print message(s)
-
-optional arguments
-	:---all: print all messages.
-	:---raw: pass raw mail string.
-	:---separately: call print command once for each message.
-
-
-
-remove
-______
-
-remove message(s) from the index
-
-optional arguments
-	:---all: remove whole thread.
-
-
-
-togglesource
-____________
-
-display message source
-
-optional arguments
-	:---all: affect all messages.
-
-
-
-retag
-_____
-
-set message(s) tags.
-
-argument
-	comma separated list of tags
-
-optional arguments
-	:---all: tag all messages in thread.
-
-
-
-fold
-____
-
-fold message(s)
-
-optional arguments
-	:---all: fold all messages.
-
-
-
-tag
-___
-
-add tags to message(s)
-
-argument
-	comma separated list of tags
-
-optional arguments
-	:---all: tag all messages in thread.
-
-
-
-untag
-_____
-
-remove tags from message(s)
-
-argument
-	comma separated list of tags
-
-optional arguments
-	:---all: tag all messages in thread.
-
-
-
-unfold
-______
-
-unfold message(s)
-
-optional arguments
-	:---all: unfold all messages.
-
-
-
-forward
-_______
-
-forward message
-
-optional arguments
-	:---attach: attach original mail.
-
-
-
-reply
-_____
-
-reply to message
-
-optional arguments
-	:---all: reply to all.
-
-
-
-save
-____
-
-save attachment(s)
-
-argument
-	path to save to
-
-optional arguments
-	:---all: save all attachments.
-
-
-
-toggletags
-__________
-
-flip presence of tags on message(s)
-
-argument
-	comma separated list of tags
-
-optional arguments
-	:---all: tag all messages in thread.
-
-
-
-select
-______
-
-select focussed element. The fired action depends on the focus:
-        - if message summary, this toggles visibility of the message,
-        - if attachment line, this opens the attachment
-
-
-
-global-mode
------------
-
-bclose
-______
-
-close current buffer
-
-
-
-
-bprevious
-_________
-
-focus previous buffer
-
-
-
-
-search
-______
-
-open a new search buffer
-
-argument
-	search string
-
-optional arguments
-	:---sort: sort order. Valid choices are: \`oldest_first\`,\`newest_first\`,\`message_id\`,\`unsorted\`.
-
-
-
-compose
-_______
-
-compose a new email
-
-optional arguments
-	:---sender: sender.
-	:---template: path to a template message file.
-	:---subject: subject line.
-	:---to: recipients.
-	:---cc: copy to.
-	:---bcc: blind copy to.
-	:---attach: attach files.
-
-
-
-prompt
-______
-
-prompts for commandline and interprets it upon select
-
-argument
-	initial content
-
-
-
-
-help
-____
-
-
-    display help for a command. Use 'bindings' to
-    display all keybings interpreted in current mode.'
-    
-
-argument
-	command or 'bindings'
-
-
-
-
-move
-____
-
-move focus
-
-argument
-	direction
-
-
-
-
-shellescape
-___________
-
-run external command
-
-argument
-	command line to execute
-
-optional arguments
-	:---spawn: run in terminal window.
-	:---thread: run in separate thread.
-	:---refocus: refocus current buffer                      after command has finished.
-
-
-
-refresh
-_______
-
-refresh the current buffer
-
-
-
-
-cancel
-______
-
-send cancel event
-
-
-
-
-pyshell
-_______
-
-open an interactive python shell for introspection
-
-
-
-
-exit
-____
-
-shut down cleanly
-
-
-
-
-flush
-_____
-
-flush write operations or retry until committed
-
-
-
-
-bufferlist
-__________
-
-open a list of active buffers
-
-
-
-
-bnext
-_____
-
-focus next buffer
-
-
-
-
-select
-______
-
-send select event
-
-
-
-
-taglist
-_______
-
-opens taglist buffer
-
-
-
-envelope-mode
--------------
-
-set
-___
-
-set header value
-
-positional arguments
-	:0: header to refine
-	:1: value
-
-
-optional arguments
-	:---append: keep previous values.
-
-
-
-toggleheaders
-_____________
-
-toggle display of all headers
-
-
-
-
-edit
-____
-
-edit mail
-
-
-
-
-send
-____
-
-send mail
-
-
-
-
-attach
-______
-
-attach files to the mail
-
-argument
-	file(s) to attach (accepts wildcads)
-
-
-
-
-refine
-______
-
-prompt to change the value of a header
-
-argument
-	header to refine
-
-
-
-
-save
-____
-
-save draft
-
-
-
-
-unset
-_____
-
-remove header field
-
-argument
-	header to refine
-
-
-
-bufferlist-mode
----------------
-
-close
-_____
-
-close focussed buffer
-
-
-
-
-select
-______
-
-focus selected buffer
-
-
-
-taglist-mode
-------------
-
-select
-______
-
-search for messages with selected tag
-
-
-
diff --git a/docs/user/source/usage/index.rst b/docs/user/source/usage/index.rst
index b9e3db73..7e97e78e 100644
--- a/docs/user/source/usage/index.rst
+++ b/docs/user/source/usage/index.rst
@@ -11,7 +11,4 @@ First Steps
 
 .. include:: first_steps.rst
 
-Commands
-========
-
 .. include:: commands.rst