docs: Update documentation

Update the docs and include a page describing the notmuch "binary"

diff --git a/README b/README
index 9caf32dc84f5965f38e87fb11bea980e5e0b7fd4..d7107b7d3ea008abf2806fcdcaa38ff479cd7711 100644 (file)
--- 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 468a3c911cb34b910328345d75c018c9354c6de5..f2b995a63ca6fb8062d548543ef111d92ccaf919 100644 (file)
--- 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 (file)
index 0000000..32e1783
--- /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 <http://bitbucket.org/spaetz/cnotmuch/src/>`_.
+
+
+It is invoked with the following pattern: `notmuch <command> [args...]`.
+
+Where <command> 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-terms> [...]  Search for messages matching the given search terms.
+
+               This has been implemented but for the `--format` and
+               `--sort` options.
+
+  **show**     <search-terms> [...]
+               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**    <search-terms> [...]
+               Count messages matching the search terms.
+
+               This has been fully implemented.
+
+  **reply**    [options...] <search-terms> [...]
+               Construct a reply template for a set of messages.
+
+               This has not been implemented yet.
+
+  **tag**      +<tag>|-<tag> [...] [--] <search-terms> [...]
+               Add/remove tags for all messages matching the search terms.
+
+               This has been fully implemented.
+
+  **dump**     [<filename>]
+               Create a plain-text dump of the tags for each message.
+
+               This has been fully implemented.
+  **restore**  <filename>
+               Restore the tags from the given dump file (see 'dump').
+
+               This has been fully implemented.
+
+  **search-tags**      [<search-terms> [...] ]
+               List all tags found in the database or matching messages.
+
+               This has been fully implemented.
+
+  **help**     [<command>]
+               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.