python: split the documentation

Move each classes documentation into its own file and thus into its
own page in the generated documentation.

Signed-off-by: Justus Winter <4winter@informatik.uni-hamburg.de>

diff --git a/bindings/python/docs/source/database.rst b/bindings/python/docs/source/database.rst
new file mode 100644 (file)
index 0000000..ee71085
--- /dev/null
+++ b/bindings/python/docs/source/database.rst
@@ -0,0 +1,48 @@
+:class:`Database` -- The underlying notmuch database
+====================================================
+
+.. currentmodule:: notmuch
+
+.. 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:: begin_atomic
+
+   .. automethod:: end_atomic
+
+   .. automethod:: get_directory
+
+   .. automethod:: add_message
+
+   .. automethod:: remove_message
+
+   .. automethod:: find_message
+
+   .. automethod:: find_message_by_filename
+
+   .. automethod:: get_all_tags
+
+   .. automethod:: create_query
+
+   .. 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

diff --git a/bindings/python/docs/source/filesystem.rst b/bindings/python/docs/source/filesystem.rst
new file mode 100644 (file)
index 0000000..685dc4d
--- /dev/null
+++ b/bindings/python/docs/source/filesystem.rst
@@ -0,0 +1,30 @@
+Files and directories
+=====================
+
+.. currentmodule:: notmuch
+
+:class:`Filenames` -- An iterator over filenames
+------------------------------------------------
+
+.. autoclass:: Filenames
+
+   .. automethod:: Filenames.__len__
+
+   .. automethod:: Filenames.as_generator
+
+:class:`Directoy` -- A directory entry in the database
+------------------------------------------------------
+
+.. autoclass:: Directory
+
+   .. automethod:: Directory.get_child_files
+
+   .. automethod:: Directory.get_child_directories
+
+   .. automethod:: Directory.get_mtime
+
+   .. automethod:: Directory.set_mtime
+
+   .. autoattribute:: Directory.mtime
+
+   .. autoattribute:: Directory.path

diff --git a/bindings/python/docs/source/index.rst b/bindings/python/docs/source/index.rst
index a2b42aae6b686ccd5da1357010a861de819c08f3..9ad5fa9759fc3e3db4e738fc8854dd07144780e3 100644 (file)
--- a/bindings/python/docs/source/index.rst
+++ b/bindings/python/docs/source/index.rst
@@ -1,272 +1,37 @@
-.. notmuch documentation master file, created by
-   sphinx-quickstart on Tue Feb  2 10:00:47 2010.
+Welcome to :mod:`notmuch`'s documentation
+=========================================
 
 .. currentmodule:: notmuch
 
-Welcome to :mod:`notmuch`'s documentation
-===========================================
-
-The :mod:`notmuch` module provides an interface to the `notmuch <http://notmuchmail.org>`_ functionality, directly interfacing to a shared notmuch library.
-Within :mod:`notmuch`, the classes :class:`Database`, :class:`Query` provide most of the core functionality, returning :class:`Threads`, :class:`Messages` and :class:`Tags`.
+The :mod:`notmuch` module provides an interface to the `notmuch
+<http://notmuchmail.org>`_ functionality, directly interfacing to a
+shared notmuch library.  Within :mod:`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).
 
-This page contains the main API overview of notmuch |release|.
-
-
-More information on specific topics can be found on the following pages:
-
 .. toctree::
    :maxdepth: 1
 
    quickstart
    notes
    status_and_errors
+   database
+   query
+   messages
+   message
+   tags
+   threads
+   thread
+   filesystem
    notmuch
 
-: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:: begin_atomic
-
-   .. automethod:: end_atomic
-
-   .. automethod:: get_directory
-
-   .. automethod:: add_message
-
-   .. automethod:: remove_message
-
-   .. automethod:: find_message
-
-   .. automethod:: find_message_by_filename
-
-   .. automethod:: get_all_tags
-
-   .. automethod:: create_query
-
-   .. 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:`Query` -- A search query
--------------------------------------------------
-
-.. 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.
-
-     SORT.UNSORTED
-       Do not apply a special sort order (returns results in document id
-       order).
-
-   .. 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:: count_threads
-
-
-:class:`Messages` -- A bunch of messages
-----------------------------------------
-
-.. autoclass:: Messages
-
-   .. automethod:: collect_tags
-
-   .. method:: __len__()
-
-   .. 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
-----------------------------------------
-
-.. autoclass:: Message
-
-   .. automethod:: get_message_id
-
-   .. automethod:: get_thread_id
-
-   .. automethod:: get_replies
-
-   .. automethod:: get_filename
-
-   .. automethod:: get_filenames
-
-   .. 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:: get_date
-
-   .. automethod:: get_header
-
-   .. automethod:: get_tags
-
-   .. automethod:: maildir_flags_to_tags
-
-   .. automethod:: tags_to_maildir_flags
-
-   .. automethod:: remove_tag
-
-   .. automethod:: add_tag
-
-   .. automethod:: remove_all_tags
-
-   .. automethod:: freeze
-
-   .. automethod:: thaw
-
-   .. automethod:: format_message_as_json
-
-   .. automethod:: format_message_as_text
-
-   .. automethod:: __str__
-
-
-:class:`Tags` -- Notmuch tags
------------------------------
-
-.. autoclass:: Tags
-   :members:
-
-   .. 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:`Threads` -- Threads iterator
------------------------------------------------------
-
-.. autoclass:: Threads
-
-   .. automethod:: __len__
-
-   .. automethod:: __str__
-
-:class:`Thread` -- A single thread
-------------------------------------
-
-.. 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
-------------------------------------------------
-
-.. autoclass:: Filenames
-
-   .. automethod:: Filenames.__len__
-
-   .. automethod:: Filenames.as_generator
-
-:class:`Directoy` -- A directory entry in the database
-------------------------------------------------------------------------
-
-.. autoclass:: Directory
-
-   .. automethod:: Directory.get_child_files
-
-   .. automethod:: Directory.get_child_directories
-
-   .. automethod:: Directory.get_mtime
-
-   .. automethod:: Directory.set_mtime
-
-   .. autoattribute:: Directory.mtime
-
-   .. autoattribute:: Directory.path
-
-
-The `next page <status_and_errors.html>`_ contains information on possible Status and Error values.
-
 Indices and tables
 ==================
 
 * :ref:`genindex`
 * :ref:`search`
-

diff --git a/bindings/python/docs/source/message.rst b/bindings/python/docs/source/message.rst
new file mode 100644 (file)
index 0000000..2ae280e
--- /dev/null
+++ b/bindings/python/docs/source/message.rst
@@ -0,0 +1,54 @@
+:class:`Message` -- A single message
+====================================
+
+.. currentmodule:: notmuch
+
+.. autoclass:: Message
+
+   .. automethod:: get_message_id
+
+   .. automethod:: get_thread_id
+
+   .. automethod:: get_replies
+
+   .. automethod:: get_filename
+
+   .. automethod:: get_filenames
+
+   .. 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:: get_date
+
+   .. automethod:: get_header
+
+   .. automethod:: get_tags
+
+   .. automethod:: maildir_flags_to_tags
+
+   .. automethod:: tags_to_maildir_flags
+
+   .. automethod:: remove_tag
+
+   .. automethod:: add_tag
+
+   .. automethod:: remove_all_tags
+
+   .. automethod:: freeze
+
+   .. automethod:: thaw
+
+   .. automethod:: format_message_as_json
+
+   .. automethod:: format_message_as_text
+
+   .. automethod:: __str__

diff --git a/bindings/python/docs/source/messages.rst b/bindings/python/docs/source/messages.rst
new file mode 100644 (file)
index 0000000..3ccf505
--- /dev/null
+++ b/bindings/python/docs/source/messages.rst
@@ -0,0 +1,15 @@
+:class:`Messages` -- A bunch of messages
+========================================
+
+.. currentmodule:: notmuch
+
+.. autoclass:: Messages
+
+   .. automethod:: collect_tags
+
+   .. method:: __len__()
+
+   .. 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))`.

diff --git a/bindings/python/docs/source/query.rst b/bindings/python/docs/source/query.rst
new file mode 100644 (file)
index 0000000..ddfc348
--- /dev/null
+++ b/bindings/python/docs/source/query.rst
@@ -0,0 +1,41 @@
+:class:`Query` -- A search query
+================================
+
+.. currentmodule:: notmuch
+
+.. 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.
+
+     SORT.UNSORTED
+       Do not apply a special sort order (returns results in document id
+       order).
+
+   .. 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:: count_threads

diff --git a/bindings/python/docs/source/tags.rst b/bindings/python/docs/source/tags.rst
new file mode 100644 (file)
index 0000000..31527d4
--- /dev/null
+++ b/bindings/python/docs/source/tags.rst
@@ -0,0 +1,17 @@
+:class:`Tags` -- Notmuch tags
+-----------------------------
+
+.. currentmodule:: notmuch
+
+.. autoclass:: Tags
+   :members:
+
+   .. 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__

diff --git a/bindings/python/docs/source/thread.rst b/bindings/python/docs/source/thread.rst
new file mode 100644 (file)
index 0000000..4067872
--- /dev/null
+++ b/bindings/python/docs/source/thread.rst
@@ -0,0 +1,26 @@
+:class:`Thread` -- A single thread
+==================================
+
+.. currentmodule:: notmuch
+
+.. 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__

diff --git a/bindings/python/docs/source/threads.rst b/bindings/python/docs/source/threads.rst
new file mode 100644 (file)
index 0000000..e5a8c8a
--- /dev/null
+++ b/bindings/python/docs/source/threads.rst
@@ -0,0 +1,10 @@
+:class:`Threads` -- Threads iterator
+====================================
+
+.. currentmodule:: notmuch
+
+.. autoclass:: Threads
+
+   .. automethod:: __len__
+
+   .. automethod:: __str__