docs: Improve documentations

[notmuch] / docs / source / index.rst

diff --git a/docs/source/index.rst b/docs/source/index.rst
index 468a3c911cb34b910328345d75c018c9354c6de5..2354190a0358b20bc03b317d2d15757564704b49 100644 (file)
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -1,19 +1,19 @@
 .. cnotmuch documentation master file, created by
    sphinx-quickstart on Tue Feb  2 10:00:47 2010.
 
 .. cnotmuch documentation master file, created by
    sphinx-quickstart on Tue Feb  2 10:00:47 2010.
 

-.. currentmodule:: cnotmuch
+.. currentmodule:: cnotmuch.notmuch

 
 Welcome to :mod:`cnotmuch`'s documentation
 ===========================================
 
 The :mod:`cnotmuch` module provides an interface to the `notmuch <http://notmuchmail.org>`_ functionality, directly interfacing to a shared notmuch library.
 
 Welcome to :mod:`cnotmuch`'s documentation
 ===========================================
 
 The :mod:`cnotmuch` module provides an interface to the `notmuch <http://notmuchmail.org>`_ functionality, directly interfacing to a shared notmuch library.

-The classes :class:`notmuch.Database`, :class:`notmuch.Query` provide most of the core functionality, returning :class:`notmuch.Messages` and :class:`notmuch.Tags`.
+Within :mod:`cnotmuch.notmuch`, the classes :class:`Database`, :class:`Query` provide most of the core functionality, returning :class:`Threads`, :class:`Messages` and :class:`Tags`.

 
 .. moduleauthor:: Sebastian Spaeth <Sebastian@SSpaeth.de>
 
 :License: This module is covered under the GNU GPL v3 (or later).
 
 
 .. moduleauthor:: Sebastian Spaeth <Sebastian@SSpaeth.de>
 
 :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::
 
 
 Notmuch can be imported as::
 


@@ -23,21 +23,24 @@ or::
 
  from cnotmuch.notmuch import Query,Database
 
 
  from cnotmuch.notmuch import Query,Database
 

+More information on specific topics can be found on the following pages:
+

 .. toctree::
    :maxdepth: 1
 
 .. toctree::
    :maxdepth: 1
 

+   notmuch   

 
 

-:mod:`notmuch` -- The Notmuch interface
-=============================================
+:mod:`cnotmuch.notmuch` -- The Notmuch interface
+=================================================

 
 .. automodule:: cnotmuch.notmuch
 
 :todo: Document nmlib,STATUS
 
 
 .. automodule:: cnotmuch.notmuch
 
 :todo: Document nmlib,STATUS
 

-:class:`Database` -- The underlying notmuch database
------------------------------------------------------
+:class:`cnotmuch.notmuch.Database` -- The underlying notmuch database
+---------------------------------------------------------------------

 
 

-.. autoclass:: Database([path=None[, create=False[, mode=MODE.READ_ONLY]]])
+.. autoclass:: cnotmuch.notmuch.Database([path=None[, create=False[, mode=MODE.READ_ONLY]]])

 
    .. automethod:: create
 
 
    .. automethod:: create
 


@@ -63,6 +66,9 @@ or::
 
    .. automethod:: create_query
 
 
    .. 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.
    .. attribute:: Database.MODE
 
      Defines constants that are used as the mode in which to open a database.


@@ -75,10 +81,10 @@ or::
 
    .. autoattribute:: db_p
 
 
    .. autoattribute:: db_p
 

-:class:`Query` -- A search query
------------------------------------------------
+:class:`cnotmuch.notmuch.Query` -- A search query
+-------------------------------------------------

 
 

-.. autoclass:: Query
+.. autoclass:: cnotmuch.notmuch.Query

 
    .. automethod:: create
 
 
    .. automethod:: create
 


@@ -97,12 +103,19 @@ or::
 
    .. automethod:: set_sort
 
 
    .. 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
 
    .. automethod:: count_messages
 
    .. automethod:: search_threads
 
    .. automethod:: search_messages
 
    .. automethod:: count_messages
 

+

 :class:`Messages` -- A bunch of messages
 ----------------------------------------
 
 :class:`Messages` -- A bunch of messages
 ----------------------------------------
 


@@ -125,7 +138,15 @@ or::
 
    .. automethod:: get_filename
 
 
    .. automethod:: get_filename
 

-   .. automethod:: get_flag
+   .. attribute:: FLAG
+
+        FLAG.MATCH 
+          This flag is automatically set by a
+         Query.search_threads on those messages that match the
+         query. This allows us to distinguish matches from the rest
+         of the messages in that thread.
+
+  .. automethod:: get_flag

 
    .. automethod:: set_flag
    
 
    .. automethod:: set_flag
    


@@ -149,6 +170,7 @@ or::
 
    .. automethod:: __str__
 
 
    .. automethod:: __str__
 

+

 :class:`Tags` -- Notmuch tags
 -----------------------------
 
 :class:`Tags` -- Notmuch tags
 -----------------------------
 


@@ -159,25 +181,65 @@ or::
 
    .. automethod:: __str__
 
 
    .. automethod:: __str__
 

-:class:`Threads` -- Threads iterator
-------------------------------------

 
 

-To be implemented
+:class:`cnotmuch.notmuch.Threads` -- Threads iterator
+-----------------------------------------------------
+
+.. autoclass:: cnotmuch.notmuch.Threads
+
+   .. automethod:: __len__
+
+   .. automethod:: __str__

 
 :class:`Thread` -- A single thread
 ------------------------------------
 
 
 :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
 ------------------------------------------------
 
 
 :class:`Filenames` -- An iterator over filenames
 ------------------------------------------------
 

-To be implemented
+.. autoclass:: cnotmuch.database.Filenames
+
+   .. automethod:: cnotmuch.database.Filenames.__len__

 
 

-:class:`Directoy` -- A directory entry in the database
-------------------------------------------------------
+:class:`cnotmuch.database.Directoy` -- A directory entry in the database
+------------------------------------------------------------------------

 
 

-To be implemented
+.. autoclass:: cnotmuch.database.Directory
+
+   .. automethod:: cnotmuch.database.Directory.get_child_files
+
+   .. automethod:: cnotmuch.database.Directory.get_child_directories
+
+   .. automethod:: cnotmuch.database.Directory.get_mtime
+
+   .. automethod:: cnotmuch.database.Directory.set_mtime
+
+   .. autoattribute:: cnotmuch.database.Directory.mtime
+
+   .. autoattribute:: cnotmuch.database.Directory.path

 
 :exc:`NotmuchError` -- A Notmuch execution error
 ------------------------------------------------
 
 :exc:`NotmuchError` -- A Notmuch execution error
 ------------------------------------------------


@@ -188,9 +250,23 @@ To be implemented
 
 :class:`STATUS` -- Notmuch operation return status
 --------------------------------------------------
 
 :class:`STATUS` -- Notmuch operation return status
 --------------------------------------------------

-.. autoclass:: STATUS

 
 

-   To be documented
+.. data:: STATUS
+
+  STATUS is a class, whose attributes provide constants that serve as return indicators for notmuch functions. Currently the following ones are defined. For possible return values and specific meaning for each method, see the method description.
+
+  * SUCCESS
+  * OUT_OF_MEMORY
+  * READ_ONLY_DATABASE
+  * XAPIAN_EXCEPTION
+  * FILE_ERROR
+  * FILE_NOT_EMAIL
+  * DUPLICATE_MESSAGE_ID
+  * NULL_POINTER
+  * TAG_TOO_LONG
+  * UNBALANCED_FREEZE_THAW
+  * NOT_INITIALIZED
+

 
 Indices and tables
 ==================
 
 Indices and tables
 ==================