python: move the usage example to quickstart.rst

[notmuch] / bindings / python / docs / source / index.rst

diff --git a/bindings/python/docs/source/index.rst b/bindings/python/docs/source/index.rst
index e9f39eb03428269bf037b1255095dc885d29d162..dec9697fd42f33d7d2e2b6b0cf9ebc0c00517de5 100644 (file)
--- a/bindings/python/docs/source/index.rst
+++ b/bindings/python/docs/source/index.rst
@@ -13,35 +13,27 @@ Within :mod:`notmuch`, the classes :class:`Database`, :class:`Query` provide mos
 
 :License: This module is covered under the GNU GPL v3 (or later).
 
-This page contains the main API overview of notmuch |release|. 
+This page contains the main API overview of notmuch |release|.
 
-Notmuch can be imported as::
-
- import notmuch
-
-or::
-
- from notmuch import Query,Database
 
 More information on specific topics can be found on the following pages:
 
 .. toctree::
    :maxdepth: 1
 
+   quickstart
    status_and_errors
-   notmuch   
+   notmuch
 
 :mod:`notmuch` -- The Notmuch interface
 =================================================
 
 .. automodule:: notmuch
 
-:todo: Document nmlib,STATUS
-
-:class:`notmuch.Database` -- The underlying notmuch database
+:class:`Database` -- The underlying notmuch database
 ---------------------------------------------------------------------
 
-.. autoclass:: notmuch.Database([path=None[, create=False[, mode=MODE.READ_ONLY]]])
+.. autoclass:: Database([path=None[, create=False[, mode=MODE.READ_ONLY]]])
 
    .. automethod:: create
 
@@ -55,6 +47,10 @@ More information on specific topics can be found on the following pages:
 
    .. automethod:: upgrade
 
+   .. automethod:: begin_atomic
+
+   .. automethod:: end_atomic
+
    .. automethod:: get_directory
 
    .. automethod:: add_message
@@ -63,13 +59,12 @@ More information on specific topics can be found on the following pages:
 
    .. automethod:: find_message
 
+   .. automethod:: find_message_by_filename
+
    .. automethod:: get_all_tags
 
    .. 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.
@@ -82,10 +77,11 @@ More information on specific topics can be found on the following pages:
 
    .. autoattribute:: db_p
 
-:class:`notmuch.Query` -- A search query
+
+:class:`Query` -- A search query
 -------------------------------------------------
 
-.. autoclass:: notmuch.Query
+.. autoclass:: Query
 
    .. automethod:: create
 
@@ -103,8 +99,8 @@ More information on specific topics can be found on the following pages:
        Sort by email message ID.
 
      SORT.UNSORTED
-       Do not apply a special sort order (returns results in document id     
-       order). 
+       Do not apply a special sort order (returns results in document id
+       order).
 
    .. automethod:: set_sort
 
@@ -120,6 +116,8 @@ More information on specific topics can be found on the following pages:
 
    .. automethod:: count_messages
 
+   .. automethod:: count_threads
+
 
 :class:`Messages` -- A bunch of messages
 ----------------------------------------
@@ -130,10 +128,10 @@ More information on specific topics can be found on the following pages:
 
    .. method:: __len__()
 
-   .. note:: :meth:`__len__` was removed in version 0.6 as it exhausted
-       the iterator and broke list(Messages()). Use the
-       :meth:`Query.count_messages` function or use
-       `len(list(msgs))`.
+   .. warning::
+
+      :meth:`__len__` was removed in version 0.6 as it exhausted the iterator and broke
+      list(Messages()). Use the :meth:`Query.count_messages` function or use `len(list(msgs))`.
 
 :class:`Message` -- A single message
 ----------------------------------------
@@ -152,7 +150,7 @@ More information on specific topics can be found on the following pages:
 
    .. attribute:: FLAG
 
-        FLAG.MATCH 
+        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
@@ -161,7 +159,7 @@ More information on specific topics can be found on the following pages:
    .. automethod:: get_flag
 
    .. automethod:: set_flag
-   
+
    .. automethod:: get_date
 
    .. automethod:: get_header
@@ -195,15 +193,21 @@ More information on specific topics can be found on the following pages:
 .. autoclass:: Tags
    :members:
 
-   .. automethod:: __len__
+   .. method:: __len__
+
+       .. warning::
+
+            :meth:`__len__` was removed in version 0.6 as it exhausted the iterator and broke
+            list(Tags()). Use :meth:`len(list(msgs))` instead if you need to know the number of
+            tags.
 
    .. automethod:: __str__
 
 
-:class:`notmuch.Threads` -- Threads iterator
+:class:`Threads` -- Threads iterator
 -----------------------------------------------------
 
-.. autoclass:: notmuch.Threads
+.. autoclass:: Threads
 
    .. automethod:: __len__
 
@@ -238,26 +242,28 @@ More information on specific topics can be found on the following pages:
 :class:`Filenames` -- An iterator over filenames
 ------------------------------------------------
 
-.. autoclass:: notmuch.database.Filenames
+.. autoclass:: Filenames
+
+   .. automethod:: Filenames.__len__
 
-   .. automethod:: notmuch.database.Filenames.__len__
+   .. automethod:: Filenames.as_generator
 
-:class:`notmuch.database.Directoy` -- A directory entry in the database
+:class:`Directoy` -- A directory entry in the database
 ------------------------------------------------------------------------
 
-.. autoclass:: notmuch.database.Directory
+.. autoclass:: Directory
 
-   .. automethod:: notmuch.database.Directory.get_child_files
+   .. automethod:: Directory.get_child_files
 
-   .. automethod:: notmuch.database.Directory.get_child_directories
+   .. automethod:: Directory.get_child_directories
 
-   .. automethod:: notmuch.database.Directory.get_mtime
+   .. automethod:: Directory.get_mtime
 
-   .. automethod:: notmuch.database.Directory.set_mtime
+   .. automethod:: Directory.set_mtime
 
-   .. autoattribute:: notmuch.database.Directory.mtime
+   .. autoattribute:: Directory.mtime
 
-   .. autoattribute:: notmuch.database.Directory.path
+   .. autoattribute:: Directory.path
 
 
 The `next page <status_and_errors.html>`_ contains information on possible Status and Error values.