From bb57345740da993584794d4071c63294da7beaa8 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Wed, 24 Mar 2010 11:05:54 +0100 Subject: [PATCH] docs: Update documentation Update the docs and include a page describing the notmuch "binary" --- README | 26 ++++++++++++++-- docs/source/index.rst | 46 ++++++++++++++++++++++++++-- docs/source/notmuch.rst | 68 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 134 insertions(+), 6 deletions(-) create mode 100644 docs/source/notmuch.rst diff --git a/README b/README index 9caf32dc..d7107b7d 100644 --- a/README +++ b/README @@ -6,9 +6,11 @@ This module makes the functionality of the notmuch library this modul depends on a libnotmuch.so|dll being available on the user's system. -If you have downloaded the full source tarball, you can create the -documentation with sphinx installed, go to the docs directory and -"make html". A static version of the documentation is available at: +If you have downloaded the full source tarball (available from +bitbucket.org, the source distribution and binary distribution come +without the documentation), you can create the documentation with +sphinx installed, go to the docs directory and "make html". A static +version of the documentation is available at: `http://spaetz.bitbucket.org`_ @@ -21,6 +23,24 @@ The original source has been provided by (c)Sebastian Spaeth, 2010. All code is available under the GNU GPLv3+ (see docs/COPYING) unless specified otherwise. +INSTALLATION & DEINSTALL +------------------------ + +cnotmuch is available on pypi.python.org. This means you can do +"easy_install cnotmuch" on your linux box and it will get installed +into: + +/usr/local/lib/python2.x/dist-packages/ + +For uninstalling, you'll need to remove the "cnotmuch-0.1-py2.x.egg" +directory and delete one entry in the "easy-install.pth" file in that +directory. + +It needs to have a libnotmuch.so or libnotmuch.so.1 available in some +library folder or will raise an exception when loading. +"OSError: libnotmuch.so.1: cannot open shared object file: No such file or directory" + + Usage ----- For more examples of how to use the cnotmuch interface, have a look at the diff --git a/docs/source/index.rst b/docs/source/index.rst index 468a3c91..f2b995a6 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -13,7 +13,7 @@ The classes :class:`notmuch.Database`, :class:`notmuch.Query` provide most of th :License: This module is covered under the GNU GPL v3 (or later). -This page contains the main API overview of cnotmuch |release|. More information on specific topics can be found on the following pages: (none here yet) +This page contains the main API overview of cnotmuch |release|. Notmuch can be imported as:: @@ -23,9 +23,12 @@ or:: from cnotmuch.notmuch import Query,Database +More information on specific topics can be found on the following pages: + .. toctree:: :maxdepth: 1 + notmuch :mod:`notmuch` -- The Notmuch interface ============================================= @@ -63,6 +66,9 @@ or:: .. automethod:: create_query + .. note:: :meth:`create_query` was broken in release + 0.1 and is fixed since 0.1.1. + .. attribute:: Database.MODE Defines constants that are used as the mode in which to open a database. @@ -97,6 +103,12 @@ or:: .. automethod:: set_sort + .. attribute:: sort + + Instance attribute :attr:`sort` contains the sort order (see + :attr:`Query.SORT`) if explicitely specified via + :meth:`set_sort`. By default it is set to `None`. + .. automethod:: search_threads .. automethod:: search_messages @@ -159,15 +171,43 @@ or:: .. automethod:: __str__ + +.. ----------------------------------------------------------------- +.. currentmodule:: cnotmuch.thread + :class:`Threads` -- Threads iterator ------------------------------------ -To be implemented +.. autoclass:: Threads + + .. automethod:: __len__ + + .. automethod:: __str__ :class:`Thread` -- A single thread ------------------------------------ -To be implemented +.. autoclass:: Thread + + .. automethod:: get_thread_id + + .. automethod:: get_total_messages + + .. automethod:: get_toplevel_messages + + .. automethod:: get_matched_messages + + .. automethod:: get_authors + + .. automethod:: get_subject + + .. automethod:: get_oldest_date + + .. automethod:: get_newest_date + + .. automethod:: get_tags + + .. automethod:: __str__ :class:`Filenames` -- An iterator over filenames ------------------------------------------------ diff --git a/docs/source/notmuch.rst b/docs/source/notmuch.rst new file mode 100644 index 00000000..32e17833 --- /dev/null +++ b/docs/source/notmuch.rst @@ -0,0 +1,68 @@ +The notmuch 'binary' +==================== + +The cnotmuch module provides *notmuch*, a python reimplementation of the standard notmuch binary for two purposes: first, to allow running the standard notmuch testsuite over the cnotmuch bindings (for correctness and performance testing) and second, to give some examples as to how to use cnotmuch. 'Notmuch' provides a command line interface to your mail database. + +A standard install via `easy_install cnotmuch` will not install the notmuch binary, however it is available in the `cnotmuch source code repository `_. + + +It is invoked with the following pattern: `notmuch [args...]`. + +Where and [args...] are as follows: + + **setup** Interactively setup notmuch for first use. + This has not yet been implemented, and will probably not be + implemented unless someone puts in the effort. + + **new** [--verbose] + Find and import new messages to the notmuch database. + + This has not been implemented yet. We cheat by calling + the regular "notmuch" binary (which must be in your path + somewhere). + + **search** [options...] [...] Search for messages matching the given search terms. + + This has been implemented but for the `--format` and + `--sort` options. + + **show** [...] + Show all messages matching the search terms. + + This has been partially implemented, we show a stub for each + found message, but do not output the full message body yet. + + **count** [...] + Count messages matching the search terms. + + This has been fully implemented. + + **reply** [options...] [...] + Construct a reply template for a set of messages. + + This has not been implemented yet. + + **tag** +|- [...] [--] [...] + Add/remove tags for all messages matching the search terms. + + This has been fully implemented. + + **dump** [] + Create a plain-text dump of the tags for each message. + + This has been fully implemented. + **restore** + Restore the tags from the given dump file (see 'dump'). + + This has been fully implemented. + + **search-tags** [ [...] ] + List all tags found in the database or matching messages. + + This has been fully implemented. + + **help** [] + This message, or more detailed help for the named command. + + The 'help' page has been implemented, help for single + commands are missing though. Patches are welcome. -- 2.26.2