From 1342ec92bc3d6bd95f8a56afed83c97b96fe5a17 Mon Sep 17 00:00:00 2001 From: Patrick Totzke Date: Thu, 14 Mar 2013 15:30:12 +0000 Subject: docstrings for Thread mode widgets --- alot/widgets/thread.py | 37 ++++++++++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/alot/widgets/thread.py b/alot/widgets/thread.py index 2be80ea5..155aa9f0 100644 --- a/alot/widgets/thread.py +++ b/alot/widgets/thread.py @@ -97,7 +97,7 @@ class FocusableText(urwid.WidgetWrap): class TextlinesList(SimpleTree): def __init__(self, content, attr=None, attr_focus=None): """ - Simpletree that contains a list of all-level-0 Text widgets + :class:`SimpleTree` that contains a list of all-level-0 Text widgets for each line in content. """ structure = [] @@ -107,6 +107,15 @@ class TextlinesList(SimpleTree): class DictList(SimpleTree): + """ + :class:`SimpleTree` that displays key-value pairs. + + The structure will obey the Tree API but will not actually be a tree + but a flat list: It contains one top-level node (displaying the k/v pair in + Columns) per pair. That is, the root will be the first pair, + its sibblings will be the other pairs and first|last_child will always + be None. + """ def __init__(self, content, key_attr, value_attr, gaps_attr=None): """ :param headerslist: list of key/value pairs to display @@ -137,7 +146,21 @@ class DictList(SimpleTree): class MessageTree(CollapsibleTree): + """ + :class:`Tree` that displays contents of a single :class:`alot.db.Message`. + + Its root node is a :class:`MessageSummaryWidget`, and its child nodes + reflect the messages content (parts for headers/attachments etc). + + Collapsing this message corresponds to showing the summary only. + """ def __init__(self, message, odd=True): + """ + :param message: Messag to display + :type message: alot.db.Message + :param odd: theme summary widget as if this is an odd line (in the message-pile) + :type odd: bool + """ self._message = message self._summaryw = MessageSummaryWidget(message, even=(not odd)) @@ -188,6 +211,10 @@ class MessageTree(CollapsibleTree): return structure def collapse_if_matches(self, querystring): + """ + collapse (and show summary only) if the :class:`alot.db.Message` + matches given `querystring` + """ self.set_position_collapsed( self.root, self._message.matches(querystring)) @@ -268,6 +295,12 @@ class MessageTree(CollapsibleTree): class ThreadTree(Tree): + """ + :class:`Tree` that parses a given :class:`alot.db.Thread` into a tree of + :class:`MessageTrees ` that display this threads individual messages. + As MessageTreess are *not* urwid widgets themself this is to be used in combination + with :class:`NestedTree` only. + """ def __init__(self, thread): self._thread = thread self.root = thread.get_toplevel_messages()[0].get_message_id() @@ -279,6 +312,7 @@ class ThreadTree(Tree): self._message = {} def accumulate(msg, odd=True): + """recursively read msg and its replies""" mid = msg.get_message_id() self._message[mid] = MessageTree(msg, odd) odd = not odd @@ -305,6 +339,7 @@ class ThreadTree(Tree): last = mid self._next_sibling_of[last] = None + # Tree API def __getitem__(self, pos): return self._message.get(pos, None) -- cgit v1.2.3 From aff9bb75043cbed26d71ea513c022e5bfb090a7c Mon Sep 17 00:00:00 2001 From: Patrick Totzke Date: Fri, 15 Mar 2013 10:17:31 +0000 Subject: docs: checkin autogenerated command docs --- docs/source/usage/modes/global.rst | 35 +++++++++++++++++++++-------------- docs/source/usage/modes/thread.rst | 30 ++++++++++++++++++++++-------- 2 files changed, 43 insertions(+), 22 deletions(-) diff --git a/docs/source/usage/modes/global.rst b/docs/source/usage/modes/global.rst index f257a5c8..f5c616d9 100644 --- a/docs/source/usage/modes/global.rst +++ b/docs/source/usage/modes/global.rst @@ -34,22 +34,12 @@ The following commands are available globally optional arguments :---sort: sort order. Valid choices are: \`oldest_first\`,\`newest_first\`,\`message_id\`,\`unsorted\`. -.. _cmd.global.compose: +.. _cmd.global.repeat: -.. describe:: compose +.. describe:: repeat - compose a new email + Repeats the command executed last time - 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. - :---omit_signature: do not add signature. - :---spawn: spawn editor in new terminal. .. _cmd.global.prompt: @@ -91,7 +81,7 @@ The following commands are available globally move focus in current buffer argument - up, down, page up, page down + up, down, page up, page down, first .. _cmd.global.shellescape: @@ -122,6 +112,23 @@ The following commands are available globally open an interactive python shell for introspection +.. _cmd.global.compose: + +.. describe:: 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. + :---omit_signature: do not add signature. + :---spawn: spawn editor in new terminal. + .. _cmd.global.exit: .. describe:: exit diff --git a/docs/source/usage/modes/thread.rst b/docs/source/usage/modes/thread.rst index 83623259..3050ff28 100644 --- a/docs/source/usage/modes/thread.rst +++ b/docs/source/usage/modes/thread.rst @@ -32,6 +32,16 @@ The following commands are available in thread mode optional arguments :---spawn: open editor in new window. +.. _cmd.thread.move: + +.. describe:: move + + move focus in current buffer + + argument + up, down, page up, page down, first + + .. _cmd.thread.untag: .. describe:: untag @@ -51,8 +61,9 @@ The following commands are available in thread mode display all headers - optional arguments - :---all: affect all messages. + argument + query used to filter messages to affect + .. _cmd.thread.print: @@ -79,8 +90,9 @@ The following commands are available in thread mode display message source - optional arguments - :---all: affect all messages. + argument + query used to filter messages to affect + .. _cmd.thread.retag: @@ -101,8 +113,9 @@ The following commands are available in thread mode fold message(s) - optional arguments - :---all: fold all messages. + argument + query used to filter messages to affect + .. _cmd.thread.tag: @@ -132,8 +145,9 @@ The following commands are available in thread mode unfold message(s) - optional arguments - :---all: unfold all messages. + argument + query used to filter messages to affect + .. _cmd.thread.forward: -- cgit v1.2.3