docs: doc improvements
[notmuch] / docs / source / index.rst
1 .. cnotmuch documentation master file, created by
2    sphinx-quickstart on Tue Feb  2 10:00:47 2010.
3
4 .. currentmodule:: cnotmuch
5
6 Welcome to :mod:`cnotmuch`'s documentation
7 ===========================================
8
9 The :mod:`cnotmuch` module provides an interface to the `notmuch <http://notmuchmail.org>`_ functionality, directly interfacing to a shared notmuch library.
10 The classes :class:`notmuch.Database`, :class:`notmuch.Query` provide most of the core functionality, returning :class:`notmuch.Messages` and :class:`notmuch.Tags`.
11
12 .. moduleauthor:: Sebastian Spaeth <Sebastian@SSpaeth.de>
13
14 :License: This module is covered under the GNU GPL v3 (or later).
15
16 This page contains the main API overview. More information on specific topics can be found on the following pages: (none here yet)
17
18 Notmuch can be imported as::
19
20  from cnotmuch import notmuch
21
22 or::
23
24  from cnotmuch.notmuch import Query,Database
25
26 .. toctree::
27    :maxdepth: 1
28
29
30 :mod:`notmuch` -- The Notmuch interface
31 =============================================
32
33 .. automodule:: cnotmuch.notmuch
34
35 :todo: Document nmlib,STATUS
36
37 :class:`Database` -- The underlying notmuch database
38 -----------------------------------------------------
39
40 .. autoclass:: Database([path=None[, create=False[, mode=MODE.READ_ONLY]]])
41
42    .. automethod:: create
43
44    .. automethod:: open(path, status=MODE.READ_ONLY)
45
46    .. automethod:: get_path
47
48    .. automethod:: find_message
49
50    .. automethod:: get_all_tags
51
52
53    .. attribute:: Database.MODE
54
55      Defines constants that are used as the mode in which to open a database.
56
57      MODE.READ_ONLY
58        Open the database in read-only mode
59
60      MODE.READ_WRITE
61        Open the database in read-write mode
62
63    .. autoattribute:: db_p
64
65 :class:`Query` -- A search query
66 -----------------------------------------------
67
68 .. autoclass:: Query
69
70    .. automethod:: create
71
72    .. attribute:: Query.SORT
73
74      Defines constants that are used as the mode in which to open a database.
75
76      SORT.OLDEST_FIRST
77        Sort by message date, oldest first.
78
79      SORT.NEWEST_FIRST
80        Sort by message date, newest first.
81
82      SORT.MESSAGE_ID
83        Sort by email message ID
84
85    .. automethod:: set_sort
86
87    .. automethod:: search_messages
88
89 :class:`Messages` -- A bunch of messages
90 ----------------------------------------
91
92 .. autoclass:: Messages
93
94    .. automethod:: collect_tags
95
96    .. automethod:: __len__
97
98 :class:`Message` -- A single message
99 ----------------------------------------
100
101 .. autoclass:: Message
102    :members:
103
104 :class:`Tags` -- Notmuch tags
105 -----------------------------
106
107 .. autoclass:: Tags
108    :members:
109
110    .. automethod:: __len__
111
112    .. automethod:: __str__
113
114 :exc:`NotmuchError` -- A Notmuch execution error
115 ------------------------------------------------
116 .. autoexception:: NotmuchError
117    :members:
118
119    This execption inherits directly from :exc:`Exception` and is raised on errors during the notmuch execution.
120
121 :class:`STATUS` -- Notmuch operation return status
122 --------------------------------------------------
123 .. autoclass:: STATUS
124    :members:
125
126 Indices and tables
127 ==================
128
129 * :ref:`genindex`
130 * :ref:`search`
131