python: document the Database.close function

Put a prominent warning into the docstring of Database.close, make the
function show up in the sphinx doc and refer to the warning in the
paragraph mentioning the context manager protocol.

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

2 files changed, 11 insertions, 1 deletions

diff --git a/bindings/python/docs/source/database.rst b/bindings/python/docs/source/database.rst
index ee71085f..2464bfff 100644
--- a/bindings/python/docs/source/database.rst
+++ b/bindings/python/docs/source/database.rst
@@ -9,6 +9,8 @@
 
    .. automethod:: open(path, status=MODE.READ_ONLY)
 
+   .. automethod:: close
+
    .. automethod:: get_path
 
    .. automethod:: get_version
diff --git a/bindings/python/notmuch/database.py b/bindings/python/notmuch/database.py
index 525f7c9a..5c62d457 100644
--- a/bindings/python/notmuch/database.py
+++ b/bindings/python/notmuch/database.py
@@ -56,7 +56,8 @@ class Database(object):
 
     :class:`Database` objects implement the context manager protocol
     so you can use the :keyword:`with` statement to ensure that the
-    database is properly closed.
+    database is properly closed. See :meth:`close` for more
+    information.
 
     .. note::
 
@@ -225,6 +226,13 @@ class Database(object):
     def close(self):
         '''
         Closes the notmuch database.
+
+        .. warning::
+
+            This function closes the notmuch database. From that point
+            on every method invoked on any object ever derived from
+            the closed database may cease to function and raise a
+            NotmuchError.
         '''
         if self._db:
             self._close(self._db)