implement Database.get_version() and Database.needs_upgrade()

[notmuch] / docs / source / index.rst

diff --git a/docs/source/index.rst b/docs/source/index.rst
index 3c7399a21df470e5251b4deee2520e26f94259b4..fc1d307e573d19ef2d5f4fbc82c61a1e2519852f 100644 (file)
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -1,50 +1,144 @@
-.. notmuch documentation master file, created by
+.. cnotmuch documentation master file, created by

    sphinx-quickstart on Tue Feb  2 10:00:47 2010.
 
    sphinx-quickstart on Tue Feb  2 10:00:47 2010.
 

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

 
 

-Welcome to notmuch's documentation!
-===================================
+Welcome to :mod:`cnotmuch`'s documentation
+===========================================

 
 

-The :mod:`notmuch` module provides an interface to the `notmuch <http://notmuchmail.org>`_ functionality. The main work horse of this module is the class :class:`Notmuch` with important other classes representing a :class:`Thread` and a single :class:`Message`.
+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`.

 
 .. moduleauthor:: Sebastian Spaeth <Sebastian@SSpaeth.de>
 
 
 .. moduleauthor:: Sebastian Spaeth <Sebastian@SSpaeth.de>
 

-:License: This module is covered under the GNU GPL v2 (or later).
+:License: This module is covered under the GNU GPL v3 (or later).

 
 

-This page contains the main API overview. More information on specific topics can be found on the following pages:
+This page contains the main API overview. More information on specific topics can be found on the following pages: (none here yet)
+
+Notmuch can be imported as::
+
+ from cnotmuch import notmuch
+
+or::
+
+ from cnotmuch.notmuch import Query,Database

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

-

 :mod:`notmuch` -- The Notmuch interface
 =============================================
 
 :mod:`notmuch` -- The Notmuch interface
 =============================================
 

-:class:`Message` -- A single email message
-------------------------------------
+.. automodule:: cnotmuch.notmuch

 
 

-.. autoclass:: Message
-   :members:
+:todo: Document nmlib,STATUS
+
+:class:`Database` -- The underlying notmuch database
+-----------------------------------------------------
+
+.. autoclass:: Database([path=None[, create=False[, mode=MODE.READ_ONLY]]])
+
+   .. automethod:: create
+
+   .. automethod:: open(path, status=MODE.READ_ONLY)
+
+   .. automethod:: get_path
+
+   .. automethod:: get_version
+
+   .. automethod:: needs_upgrade
+
+   .. automethod:: upgrade
+
+   .. automethod:: get_directory
+
+   .. automethod:: add_message
+
+   .. automethod:: remove_message
+
+   .. automethod:: find_message
+
+   .. automethod:: get_all_tags
+
+
+   .. attribute:: Database.MODE
+
+     Defines constants that are used as the mode in which to open a database.
+
+     MODE.READ_ONLY
+       Open the database in read-only mode
+
+     MODE.READ_WRITE
+       Open the database in read-write mode
+
+   .. autoattribute:: db_p

 
 

-:class:`Thread` -- Represents a message thread
+:class:`Query` -- A search query

 -----------------------------------------------
 
 -----------------------------------------------
 

-.. autoclass:: Thread
-   :members:
+.. autoclass:: Query
+
+   .. automethod:: create
+
+   .. attribute:: Query.SORT
+
+     Defines constants that are used as the mode in which to open a database.
+
+     SORT.OLDEST_FIRST
+       Sort by message date, oldest first.
+
+     SORT.NEWEST_FIRST
+       Sort by message date, newest first.
+
+     SORT.MESSAGE_ID
+       Sort by email message ID
+
+   .. automethod:: set_sort
+
+   .. automethod:: search_messages
+
+:class:`Messages` -- A bunch of messages
+----------------------------------------
+
+.. autoclass:: Messages
+
+   .. automethod:: collect_tags
+
+   .. automethod:: __len__

 
 

-   .. note:: A Thread is what a call to notmuch.show() will return, containing a bunch of :class:`Message`\ s.
+:class:`Message` -- A single message
+----------------------------------------

 
 

-:class:`Notmuch` -- A notmuch call
-------------------------------------
+.. autoclass:: Message
+
+   .. automethod:: get_message_id
+
+   .. automethod:: get_date
+
+   .. automethod:: get_header
+
+   .. automethod:: get_filename
+
+   .. automethod:: get_tags
+
+   .. automethod:: remove_tag

 
 

-.. autoclass:: Notmuch
+   .. automethod:: add_tag
+
+   .. automethod:: format_as_text
+
+   .. automethod:: __str__
+
+:class:`Tags` -- Notmuch tags
+-----------------------------
+
+.. autoclass:: Tags

    :members:
 
    :members:
 

-   .. data: '__notmuchcmd__'
+   .. automethod:: __len__

 
 

-      This is the actual binary that will be executed in order to run a notmuch command. This is set to *notmuch* and should usually not be changed.
+   .. automethod:: __str__

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


@@ -53,6 +147,11 @@ This page contains the main API overview. More information on specific topics ca
 
    This execption inherits directly from :exc:`Exception` and is raised on errors during the notmuch execution.
 
 
    This execption inherits directly from :exc:`Exception` and is raised on errors during the notmuch execution.
 

+:class:`STATUS` -- Notmuch operation return status
+--------------------------------------------------
+.. autoclass:: STATUS
+   :members:
+

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