diff options
| -rw-r--r-- | docs/api/Makefile | 4 | ||||
| -rw-r--r-- | docs/api/index.rst | 40 | ||||
| -rw-r--r-- | docs/api/source/accounts.rst (renamed from docs/api/accounts.rst) | 0 | ||||
| -rw-r--r-- | docs/api/source/commands.rst (renamed from docs/api/commands.rst) | 0 | ||||
| -rw-r--r-- | docs/api/source/conf.py (renamed from docs/api/conf.py) | 0 | ||||
| -rw-r--r-- | docs/api/source/database.rst (renamed from docs/api/database.rst) | 0 | ||||
| -rw-r--r-- | docs/api/source/index.rst | 63 | ||||
| -rw-r--r-- | docs/api/source/interface.rst (renamed from docs/api/interface.rst) | 0 | ||||
| -rw-r--r-- | docs/api/source/settings.rst (renamed from docs/api/settings.rst) | 0 | ||||
| -rw-r--r-- | docs/api/source/utils.rst (renamed from docs/api/utils.rst) | 0 | ||||
| -rw-r--r-- | docs/user/source/manpage.rst | 5 | ||||
| -rw-r--r-- | docs/user/source/usage/commands.rst | 561 | ||||
| -rw-r--r-- | docs/user/source/usage/synopsis.rst | 6 |
13 files changed, 637 insertions, 42 deletions
diff --git a/docs/api/Makefile b/docs/api/Makefile index 741cc0f0..b4d9a3dd 100644 --- a/docs/api/Makefile +++ b/docs/api/Makefile @@ -5,12 +5,12 @@ SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = -BUILDDIR = _build +BUILDDIR = build # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest diff --git a/docs/api/index.rst b/docs/api/index.rst deleted file mode 100644 index feffd544..00000000 --- a/docs/api/index.rst +++ /dev/null @@ -1,40 +0,0 @@ -`alot` API overview -==================== - -.. module:: alot - -The main component is :class:`alot.ui.UI`, which provides methods for user input and notifications, -sets up an :mod:`urwid` :class:`mainloop <urwid.main_loop.TwistedEventLoop>` and widget tree and -maintains the list of active buffers. Moreover, it integrates different "managers" responsible for -core functionalities: - -* a :class:`~db.DBManager` to access the email database -* an :class:`~account.AccountManager` to deal with user accounts -* a :class:`~settings.AlotConfigParser` (subclasses :class:`configparser.ConfigParser`) for user settings - -Every user action, triggered either by keybindings or as input to the commandprompt, is -given as commandline string that gets :func:`translated <commands.commandfactory>` -to a :class:`~commands.Command` which is then :meth:`applied <ui.UI.apply_command>`. -Different actions are defined as a subclasses of :class:`~commands.Command`, which live -in `alot/commands/MODE.py`, where MODE is the name of the mode (:class:`Buffer` type) they -are used in. - -Contents: - -.. toctree:: - :maxdepth: 1 - - database - interface - settings - accounts - utils - commands - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`search` - diff --git a/docs/api/accounts.rst b/docs/api/source/accounts.rst index c09b43fa..c09b43fa 100644 --- a/docs/api/accounts.rst +++ b/docs/api/source/accounts.rst diff --git a/docs/api/commands.rst b/docs/api/source/commands.rst index f38ac04c..f38ac04c 100644 --- a/docs/api/commands.rst +++ b/docs/api/source/commands.rst diff --git a/docs/api/conf.py b/docs/api/source/conf.py index 0c36a73f..0c36a73f 100644 --- a/docs/api/conf.py +++ b/docs/api/source/conf.py diff --git a/docs/api/database.rst b/docs/api/source/database.rst index 00334a4b..00334a4b 100644 --- a/docs/api/database.rst +++ b/docs/api/source/database.rst diff --git a/docs/api/source/index.rst b/docs/api/source/index.rst new file mode 100644 index 00000000..f9e0cf15 --- /dev/null +++ b/docs/api/source/index.rst @@ -0,0 +1,63 @@ +`alot` Developer Manual +*********************** + +.. module:: alot + +Birds eye on alot internals +=========================== +The main component is :class:`alot.ui.UI`, which provides methods for user input and notifications, +sets up an :mod:`urwid` :class:`mainloop <urwid.main_loop.TwistedEventLoop>` and widget tree and +maintains the list of active buffers. Moreover, it integrates different "managers" responsible for +core functionalities: + +* a :class:`~db.DBManager` to access the email database +* an :class:`~account.AccountManager` to deal with user accounts +* a :class:`~settings.AlotConfigParser` (subclasses :class:`configparser.ConfigParser`) for user settings + +Every user action, triggered either by keybindings or as input to the commandprompt, is +given as commandline string that gets :func:`translated <commands.commandfactory>` +to a :class:`~commands.Command` which is then :meth:`applied <ui.UI.apply_command>`. +Different actions are defined as a subclasses of :class:`~commands.Command`, which live +in `alot/commands/MODE.py`, where MODE is the name of the mode (:class:`Buffer` type) they +are used in. + +Contributing +============ + +Development is coordinated entirely via the projects `github page <https://github.com/pazz/alot>`_ +especially the `issue tracker <https://github.com/pazz/alot/issues>`_. +Current HEAD can be found in branch `testing` from `git@github.com:pazz/alot.git`. + +You can send patches to notmuch's mailing list but pull requests on github are preferred. +Here are a few more things you should know and check before you send pull requests: + +* Follow :pep:`8`. This means in particular a maximum linewidth of *79* and no trailing + white spaces. If in doubt, use an `automatic tool <http://pypi.python.org/pypi/pep8>`_ + to verify your code. + +* don't check in :file:`alot/VERSION`. Our current solution for autogenerated version + strings will update the content of this file when calling `setup.py` but we need + this file checked in as fallback for the installation to succeed from tarballs. So:: + + git update-index --assume-unchanged alot/VERSION + +* Document! Needless to say, we want readable and well documented code. Moreover, + + * Please use `sphinx directives <http://sphinx.pocoo.org/rest.html>`_ to document + the parameters and return values of your methods so that we maintain up-to-date API docs. + * Make sure your patch doesn't break the API docs. The build service at `readthedocs.org <http:alot.rtfd.org>`_ + is fragile when it comes to new import statements in our code. + * If you implemented a new feature please update the user manual in :file:`/docs/user` accordingly. + +Contents +======== + +.. toctree:: + :maxdepth: 1 + + database + interface + settings + accounts + utils + commands diff --git a/docs/api/interface.rst b/docs/api/source/interface.rst index 75b7d5c3..75b7d5c3 100644 --- a/docs/api/interface.rst +++ b/docs/api/source/interface.rst diff --git a/docs/api/settings.rst b/docs/api/source/settings.rst index f7272756..f7272756 100644 --- a/docs/api/settings.rst +++ b/docs/api/source/settings.rst diff --git a/docs/api/utils.rst b/docs/api/source/utils.rst index 8cfae2b7..8cfae2b7 100644 --- a/docs/api/utils.rst +++ b/docs/api/source/utils.rst diff --git a/docs/user/source/manpage.rst b/docs/user/source/manpage.rst index b83409d0..ae62bce7 100644 --- a/docs/user/source/manpage.rst +++ b/docs/user/source/manpage.rst @@ -19,3 +19,8 @@ Description Usage ----- .. include:: usage/first_steps.rst + + +See Also +----- +:manpage:`alot.rc(5)` diff --git a/docs/user/source/usage/commands.rst b/docs/user/source/usage/commands.rst index e69de29b..799176b9 100644 --- a/docs/user/source/usage/commands.rst +++ b/docs/user/source/usage/commands.rst @@ -0,0 +1,561 @@ +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/synopsis.rst b/docs/user/source/usage/synopsis.rst index f26ea6e1..c18bfa03 100644 --- a/docs/user/source/usage/synopsis.rst +++ b/docs/user/source/usage/synopsis.rst @@ -16,6 +16,12 @@ Options --version Display version string and exit --help Display help and exit +% .. option:: -m <module>, --module <module> +% +% Run a module as a script. +% + + Commands search |