Merge lp:~jderose/microfiber/doctest into lp:microfiber

[Jason Gerard DeRose]

At long last, this is getting fixed! A few notes to help understand the diff:

1) We've always run doctests for examples in the docstrings in the Microfiber source code itself... this change only enables doctests for examples in the Sphinx documentation (doc/*.rst), and fixes those examples so they actually pass

2) When the Microfiber documentation was originally written, we didn't have a way to create throw-away CouchDB instances for unit testing and for docstrings, but now we have usercouch.misc.TempCouch, so lot of the diff is just adding this sort of thing:

>>> from usercouch.misc import TempCouch
>>> couch = TempCouch()
>>> env = couch.bootstrap()
>>> from microfiber import Server, Database
>>> server = Server(env)
>>> db = Database('mydb', env)

3) `setup.py test` will now run the Sphinx doctests under the invoking Python interpreter; the reason for this is so these tests get run all `py3versions` we're building for; for example, currently in trusty `setup.py test` will get called both for python3.3 and python3.4; however, we only build the HTML documentation once, under python3.4, which is the default python3 version in Trusty; this will make more sense if you look at our debian/rules:

  http://bazaar.launchpad.net/~microfiber/microfiber/trunk/view/head:/debian/rules

4) The big motivator is now that Microfiber has it's own CouchDB replicator, this is a good opportunity to clearly document the CouchDB replication protocol with examples that get automatically tested! (But note the replicator docstring examples are currently only in microfiber/replicator.py, aren't yet in the Sphinx documentation.)

And some things that still need to be fixed, but were left out as this merge is already pretty big:

1) doc/microfiber.rst still has a lot of "doctest: +SKIP" in places where we should have unit tests that actually run thanks to TempCouch; but for now, I tried to focus on the minimal change needed to get all existing Sphinx doctests running and passing

2) Likewise, microfiber/__init__.py still has a lot of "doctest: +SKIP" in places where we should have unit tests that actually run thanks to TempCouch

3) I couldn't resist doing at least some stylistic improvement in doc/couchdb_api.rst, but I restrained myself from doing this everywhere for the sake of keeping this merge of a sane size; in a later merge we should finish this work and make all the documentation consistent.

[Zygmunt Krynicki (zyga)]

1401 +def run_sphinx_doctest():
1402 + sphinx_build = '/usr/share/sphinx/scripts/python3/sphinx-build'

How about executing setup.py with build_shpinx -b doctest?

[Jason Gerard DeRose (jderose)]

Zygmunt,

So do you mean add a custom "build_sphinx" command to setup.py, or is there some magical setup command included in sphinx that I should be using?

I have mixed feelings about how I'm currently running the doctests from setup.py, but I think it works well enough for a first-pass anyway. I hate using the hard-coded sphinx-build path, but that's the only way to get it to do the right thing if you have both python3-sphinx and python-sphinx installed (which is a common scenario for developers, I think).

On the build servers it's not a problem because python-sphinx wont be installed, as we don't build-depend on it.

Anyway, thanks for taking a look!

[David Jordan (dmj726)]

Approved.

review: Approve

[Zygmunt Krynicki (zyga)]

Jason: there is a build_sphinx command in setup() if you use setuptools, yes. If you're building documentation depending on python3-sphinx is a simple way to get that done. See lp:checkbox (see plainbox inside for an example)

=== modified file '.bzrignore'
--- .bzrignore	2013-02-21 01:24:23 +0000
+++ .bzrignore	2014-02-23 01:42:08 +0000
@@ -1,2 +1,2 @@
 build/
-doc/_build/
+doc/_build/*

=== modified file 'doc/couchdb_api.rst'
--- doc/couchdb_api.rst	2012-09-22 12:46:46 +0000
+++ doc/couchdb_api.rst	2014-02-23 01:42:08 +0000
@@ -4,11 +4,17 @@
 
 .. py:currentmodule:: microfiber
 
-This is a quick tour of the CouchDB REST API, as you would use it from
-Microfiber.  This is indented as a quick reference, and as such not all the API
-is documented here.  For more details, see the full `CouchDB REST API`_.
-
-.. _`CouchDB REST API`: http://couchdb.readthedocs.org/en/latest/index.html
+This is a tour of some key aspects of CouchDB REST API, as used from Microfiber.
+This is intended as a quick reference, and as such not all the API is documented
+here.  For that, see the full `CouchDB REST API`_ documentation.
+
+All the examples below need the following setup:
+
+>>> from usercouch.misc import TempCouch
+>>> from microfiber import Database, Server, dumps
+
+.. _`CouchDB REST API`: http://couchdb.readthedocs.org/en/latest/api/index.html
+
 
 
 Databases
@@ -18,108 +24,201 @@
 instance, but you can do the same using a :class:`Server` instance.
 
 
-Create
-------
-
-**PUT /db**
+``PUT /db``
+-----------
 
 This will create a new CouchDB database.  A :exc:`PreconditionFailed` exception
 is raised if a database with the same name already exists.
 
-Using a :class:`Database`:
-
->>> db = Database('mydb')
->>> db.put(None)
-{'ok': True}
-
-
-Or using a :class:`Server`:
-
->>> s = Server()
->>> s.put(None, 'mydb')
-{'ok': True}
-
-
-Retrieve
---------
-
-**GET /db**
-
-This will retrieve useful information about the database.  A :exc:`NotFound`
-exception is raised if the database does not exist.
-
-Using a :class:`Database`:
-
->>> db = Database('mydb')
+As setup for our examples, we'll do this:
+
+>>> couch = TempCouch()
+>>> env = couch.bootstrap()
+>>> server = Server(env)
+>>> db = Database('db2', env)
+
+Now we'll create "db1" using our :class:`Server`:
+
+>>> server.put(None, 'db1')
+{'ok': True}
+
+And then we'll create "db2" using our :class:`Database`:
+
+>>> db.put(None)
+{'ok': True}
+
+A :exc:`PreconditionFailed` will be raised if we try again to create "db1":
+
+>>> server.put(None, 'db1')
+Traceback (most recent call last):
+  ...
+microfiber.PreconditionFailed: 412 Precondition Failed: PUT /db1
+
+Likewise, a :exc:`PreconditionFailed` will be raised if we try again to
+create "db2":
+
+>>> db.put(None)
+Traceback (most recent call last):
+  ...
+microfiber.PreconditionFailed: 412 Precondition Failed: PUT /db2/
+
+
+``GET /db``
+-----------
+
+This will return a ``dict`` with useful information about the database.  A
+:exc:`NotFound` exception is raised if the database does not exist.
+
+Using a :class:`Database`, when the database does *not* exist:
+
+>>> couch = TempCouch()
+>>> db = Database('mydb', couch.bootstrap())
 >>> db.get()
-{'update_seq': 0, 'disk_size': 79, 'purge_seq': 0, 'doc_count': 0, 'compact_running': False, 'db_name': 'mydb', 'doc_del_count': 0, 'instance_start_time': '1314934043214745', 'committed_update_seq': 0, 'disk_format_version': 5}
-
-
-Or using a :class:`Server`:
-
->>> s = Server(env)
+Traceback (most recent call last):
+  ...
+microfiber.NotFound: 404 Object Not Found: GET /mydb/
+
+Or using a :class:`Database`, when the database exists:
+
+>>> db.put(None)
+{'ok': True}
+>>> sorted(db.get())
+['committed_update_seq', 'compact_running', 'data_size', 'db_name', 'disk_format_version', 'disk_size', 'doc_count', 'doc_del_count', 'instance_start_time', 'purge_seq', 'update_seq']
+
+Using a :class:`Server`, when the database does *not* exist:
+
+>>> couch = TempCouch()
+>>> s = Server(couch.bootstrap())
 >>> s.get('mydb')
-{'update_seq': 0, 'disk_size': 79, 'purge_seq': 0, 'doc_count': 0, 'compact_running': False, 'db_name': 'mydb', 'doc_del_count': 0, 'instance_start_time': '1314934043214745', 'committed_update_seq': 0, 'disk_format_version': 5}
-
-
-Changes
--------
-
-**GET /db/_changes**
+Traceback (most recent call last):
+  ...
+microfiber.NotFound: 404 Object Not Found: GET /mydb/
+
+Or using a :class:`Server`, when the database exists:
+
+>>> s.put(None, 'mydb')
+{'ok': True}
+>>> sorted(s.get('mydb'))
+['committed_update_seq', 'compact_running', 'data_size', 'db_name', 'disk_format_version', 'disk_size', 'doc_count', 'doc_del_count', 'instance_start_time', 'purge_seq', 'update_seq']
+
+
+``GET /db/_changes``
+--------------------
 
 Using a :class:`Database`:
 
->>> db = Database('mydb')
->>> db.get('_changes')
-{'last_seq': 0, 'results': []}
-
+>>> couch = TempCouch()
+>>> env = couch.bootstrap()
+>>> db = Database('mydb', env)
+>>> db.put(None)
+{'ok': True}
+>>> doc = {'_id': 'mydoc'}
+>>> doc['_rev'] = db.post(doc)['rev']
+>>> changes = db.get('_changes')
+>>> print(dumps(changes, pretty=True))
+{
+    "last_seq": 1,
+    "results": [
+        {
+            "changes": [
+                {
+                    "rev": "1-967a00dff5e02add41819138abb3284d"
+                }
+            ],
+            "id": "mydoc",
+            "seq": 1
+        }
+    ]
+}
 
 Or using a :class:`Server`:
 
->>> s = Server()
->>> s.get('mydb', '_changes')
-{'last_seq': 0, 'results': []}
-
-
-Compact
--------
-
-**POST /db/_compact**
-
-Using a :class:`Database`:
-
->>> db = Database('mydb')
+>>> s = Server(env)
+>>> changes = s.get('mydb', '_changes')
+>>> print(dumps(changes, pretty=True))
+{
+    "last_seq": 1,
+    "results": [
+        {
+            "changes": [
+                {
+                    "rev": "1-967a00dff5e02add41819138abb3284d"
+                }
+            ],
+            "id": "mydoc",
+            "seq": 1
+        }
+    ]
+}
+
+
+``POST /db/_compact``
+---------------------
+
+This will trigger database compaction.  Note this has no effect if compaction
+is already running (in other words, only a single compaction task will ever be
+running per database).  As setup for our examples, we'll do this:
+
+>>> couch = TempCouch()
+>>> env = couch.bootstrap()
+>>> server = Server(env)
+>>> server.put(None, 'db1')
+{'ok': True}
+>>> db = Database('db2', env)
+>>> db.put(None)
+{'ok': True}
+
+To compact "db1" using our :class:`Server`:
+
+>>> server.post(None, 'db1', '_compact')
+{'ok': True}
+
+And to compact "db2" using our :class:`Database`:
+
 >>> db.post(None, '_compact')
 {'ok': True}
 
 
-Or using a :class:`Server`:
-
->>> s = Server()
->>> s.post(None, 'mydb', '_compact')
-{'ok': True}
-
-
-Delete
-------
-
-**DELETE /db**
-
-This will delete the CouchDB database.  A :exc:`NotFound` exception is raised if
-the database does not exist.
-
-Using a :class:`Database`:
-
->>> db = Database('mydb')
->>> db.delete()
-{'ok': True}
-
-
-Or using a :class:`Server`:
-
->>> s = Server()
->>> s.delete('mydb')
-{'ok': True}
+``DELETE /db``
+--------------
+
+This will delete the CouchDB database.  As setup for our examples, we'll do
+this:
+
+>>> couch = TempCouch()
+>>> env = couch.bootstrap()
+>>> server = Server(env)
+>>> server.put(None, 'db1')
+{'ok': True}
+>>> db = Database('db2', env)
+>>> db.put(None)
+{'ok': True}
+
+For example, to delete "db1" using our :class:`Server`:
+
+>>> server.delete('db1')
+{'ok': True}
+
+Or to delete "db2' using our :class:`Database`:
+
+>>> db.delete()
+{'ok': True}
+
+A :exc:`NotFound` exception is raised if the database does not exist.  For
+example, if we try to delete the now non-existent "db1" using our
+:class:`Server`:
+
+>>> server.delete('db1')
+Traceback (most recent call last):
+  ...
+microfiber.NotFound: 404 Object Not Found: DELETE /db1
+
+And if we try to delete the now non-existent "db2" using our :class:`Database`:
+
+>>> db.delete()
+Traceback (most recent call last):
+  ...
+microfiber.NotFound: 404 Object Not Found: DELETE /db2
 
 
 
@@ -130,99 +229,298 @@
 instance, but you can do the same using a :class:`Server` instance.
 
 
-Create
-------
-
-**POST /db**
-
-This will create a new document.  A :exc:`Conflict` exception is raised if the
-document already exists.
-
-Using a :class:`Database`:
-
->>> db = Database('mydb')
->>> db.post({'_id': 'mydoc'})
-{'rev': '1-967a00dff5e02add41819138abb3284d', 'ok': True, 'id': 'mydoc'}
-
-
-Or using a :class:`Server`:
-
->>> s = Server()
->>> s.post({'_id': 'mydoc'}, 'mydb')
-{'rev': '1-967a00dff5e02add41819138abb3284d', 'ok': True, 'id': 'mydoc'}
-
-
-
-Update
-------
-
-**POST /db**
-
-This will update an existing document.  A :exc:`Conflict` exception is raised if
-``doc['_rev']`` doesn't match the latest revision of the document in CouchDB
-(meaning the document has been updated since you last retrieved it).
-
-Using a :class:`Database`:
-
->>> db = Database('mydb')
->>> db.post({'_id': 'mydoc', '_rev': '1-967a00dff5e02add41819138abb3284d'})
-{'rev': '2-7051cbe5c8faecd085a3fa619e6e6337', 'ok': True, 'id': 'mydoc'}
-
-
-Or using a :class:`Server`:
-
->>> s = Server()
->>> s.post({'_id': 'mydoc', '_rev': '1-967a00dff5e02add41819138abb3284d'}, 'mydb')
-{'rev': '2-7051cbe5c8faecd085a3fa619e6e6337', 'ok': True, 'id': 'mydoc'}
-
-
-
-Retrieve
---------
-
-**GET /db/doc**
-
-A :exc:`NotFound` exception is raised if the document does not exist.
-
-Using a :class:`Database`:
-
->>> db = Database('mydb')
+``PUT /db/doc``
+---------------
+
+This can be used to create a new document, and likewise to update an existing
+document.
+
+.. note::
+
+    :meth:`Database.save()` is a better way to create and update documents as
+    it will automatically update ``doc['_rev']`` in-place for you
+
+As setup for our examples, we'll do this:
+
+>>> couch = TempCouch()
+>>> env = couch.bootstrap()
+>>> server = Server(env)
+>>> db = Database('mydb', env)
+>>> db.put(None)
+{'ok': True}
+
+For example, we'll create "doc1" using our :class:`Server`:
+
+>>> server.put({'foo': 'bar'}, 'mydb', 'doc1')['rev']
+'1-4c6114c65e295552ab1019e2b046b10e'
+
+And we'll create "doc2" using our :class:`Database`:
+
+>>> db.put({'foo': 'bar'}, 'doc2')['rev']
+'1-4c6114c65e295552ab1019e2b046b10e'
+
+
+``POST /db``
+------------
+
+This can be used to create a new document, and likewise to update an existing
+document.
+
+.. note::
+
+    :meth:`Database.save()` is a better way to create and update documents as
+    it will automatically update ``doc['_rev']`` in-place for you
+
+As setup for our examples, we'll do this:
+
+>>> couch = TempCouch()
+>>> env = couch.bootstrap()
+>>> server = Server(env)
+>>> db = Database('mydb', env)
+>>> db.put(None)
+{'ok': True}
+
+For example, we can create "doc1" using our :class:`Server`:
+
+>>> doc1 = {'_id': 'doc1'}
+>>> doc1['_rev'] = server.post(doc1, 'mydb')['rev']
+>>> doc1['_rev']
+'1-967a00dff5e02add41819138abb3284d'
+
+And we can create "doc2" using our :class:`Database`:
+
+>>> doc2 = {'_id': 'doc2'}
+>>> doc2['_rev'] = db.post(doc2)['rev']
+>>> doc2['_rev']
+'1-967a00dff5e02add41819138abb3284d'
+
+When updated a document, ``doc['_rev']`` must be included, otherwise a
+:exc:`Conflict` exception will be raised.
+
+Note that above we updated ``doc1`` and ``doc2`` in-place with the correct
+revision.  So now we can update "doc1" using our :class:`Server` like this:
+
+>>> server.post(doc1, 'mydb')['rev']
+'2-7051cbe5c8faecd085a3fa619e6e6337'
+
+And update "doc2" using our :class:`Database` like this:
+
+>>> db.post(doc2)['rev']
+'2-7051cbe5c8faecd085a3fa619e6e6337'
+
+A :exc:`Conflict` exception is raised if ``doc['_rev']`` doesn't match the
+latest revision of the document in CouchDB (meaning the document has been
+updated since you last retrieved it).
+
+Note that in the above updates, we did not update ``doc1`` and ``doc2`` with the
+correct revision:
+
+>>> print(dumps(doc1))
+{"_id":"doc1","_rev":"1-967a00dff5e02add41819138abb3284d"}
+>>> print(dumps(doc2))
+{"_id":"doc2","_rev":"1-967a00dff5e02add41819138abb3284d"}
+
+So when we try to update "doc1" this time using our :class:`Server`, a
+:exc:`Conflict` will be raised:
+
+>>> server.post(doc1, 'mydb')
+Traceback (most recent call last):
+  ...
+microfiber.Conflict: 409 Conflict: POST /mydb
+
+And likewise when we try to update "doc2" using our :class:`Database`:
+
+>>> db.post(doc2)
+Traceback (most recent call last):
+  ...
+microfiber.Conflict: 409 Conflict: POST /
+
+
+``GET /db/doc``
+---------------
+
+This will retrieve a document from a database.  As setup for our examples, we'll
+do this:
+
+>>> couch = TempCouch()
+>>> env = couch.bootstrap()
+>>> server = Server(env)
+>>> db = Database('mydb', env)
+>>> db.put(None)
+{'ok': True}
+
+A :exc:`NotFound` exception is raised if the document does not exist.  For
+example, using our :class:`Server`:
+
+>>> server.get('mydb', 'mydoc')
+Traceback (most recent call last):
+  ...
+microfiber.NotFound: 404 Object Not Found: GET /mydb/mydoc
+
+Or using our :class:`Database`:
+
 >>> db.get('mydoc')
-{'_rev': '2-7051cbe5c8faecd085a3fa619e6e6337', '_id': 'mydoc'}
-
-
-Or using a :class:`Server`:
-
->>> s = Server()
->>> s.get('mydb', 'mydoc')
-{'_rev': '2-7051cbe5c8faecd085a3fa619e6e6337', '_id': 'mydoc'}
-
-
-
-Delete
-------
-
-**DELETE /db/doc**
-
-This will delete a document.  A :exc:`NotFound` exception is raised if the
-document does not exist.
-
-A :exc:`Conflict` exception is raised if the *rev* keyword argument doesn't
+Traceback (most recent call last):
+  ...
+microfiber.NotFound: 404 Object Not Found: GET /mydb/mydoc
+
+On the other hand, if we create "mydoc":
+
+>>> mydoc = {'_id': 'mydoc'}
+>>> mydoc['_rev'] = db.post(mydoc)['rev']
+>>> mydoc['_rev']
+'1-967a00dff5e02add41819138abb3284d'
+
+We can retrieve it using our :class:`Server`:
+
+>>> doc = server.get('mydb', 'mydoc')
+>>> print(dumps(doc, pretty=True))
+{
+    "_id": "mydoc",
+    "_rev": "1-967a00dff5e02add41819138abb3284d"
+}
+
+Or retrieve it using our :class:`Database`:
+
+>>> doc = db.get('mydoc')
+>>> print(dumps(doc, pretty=True))
+{
+    "_id": "mydoc",
+    "_rev": "1-967a00dff5e02add41819138abb3284d"
+}
+
+If you supply the *rev* keyword argument, you can retrieve the contents of an
+older revisions of a document (assuming the database hasn't yet been compacted).
+
+.. warning::
+
+    You should *never* assume that older document revisions will be available!
+    When a database is compacted, only the latest revision of each document
+    will be preserved!
+
+    The term "revision" is quite suggestive, but CouchDB is *not* a version
+    control system.  CouchDB uses "revisions" as a concurrency control
+    mechanism, and nothing more.
+
+For example, let's create a new revision of "mydoc":
+
+>>> mydoc['message'] = 'hello, world'
+>>> db.post(mydoc)['rev']
+'2-91babf69deda1e2767615ba457c80807'
+
+We can explicitly retrieve ``'2-91babf69deda1e2767615ba457c80807'`` (which also
+happens to be the latest revision):
+
+>>> doc = db.get('mydoc', rev='2-91babf69deda1e2767615ba457c80807')
+>>> print(dumps(doc, pretty=True))
+{
+    "_id": "mydoc",
+    "_rev": "2-91babf69deda1e2767615ba457c80807",
+    "message": "hello, world"
+}
+
+Or we can retrieve ``'1-967a00dff5e02add41819138abb3284d'``, the previous
+revision:
+
+>>> doc = db.get('mydoc', rev='1-967a00dff5e02add41819138abb3284d')
+>>> print(dumps(doc, pretty=True))
+{
+    "_id": "mydoc",
+    "_rev": "1-967a00dff5e02add41819138abb3284d"
+}
+
+
+``DELETE /db/doc``
+------------------
+
+This will delete a document from a database.  Note that a small document
+tombstone will still exist so that the deletion can be replicated between nodes.
+
+>>> couch = TempCouch()
+>>> env = couch.bootstrap()
+>>> server = Server(env)
+>>> db = Database('mydb', env)
+>>> db.put(None)
+{'ok': True}
+
+For example, using a :class:`Server`:
+
+>>> server.post({'_id': 'doc1'}, 'mydb')['rev']
+'1-967a00dff5e02add41819138abb3284d'
+>>> server.delete('mydb', 'doc1', rev='1-967a00dff5e02add41819138abb3284d')['rev']
+'2-eec205a9d413992850a6e32678485900'
+
+Or using a :class:`Database`:
+
+>>> db.post({'_id': 'doc2'})['rev']
+'1-967a00dff5e02add41819138abb3284d'
+>>> db.delete('doc2', rev='1-967a00dff5e02add41819138abb3284d')['rev']
+'2-eec205a9d413992850a6e32678485900'
+
+A :exc:`NotFound` exception is raised if the document does not exist.  For
+example, using a :class:`Server`:
+
+>>> server.delete('mydb', 'mydoc')
+Traceback (most recent call last):
+  ...
+microfiber.NotFound: 404 Object Not Found: DELETE /mydb/mydoc
+
+Or using a :class:`Database`:
+
+>>> db.delete('mydoc')
+Traceback (most recent call last):
+  ...
+microfiber.NotFound: 404 Object Not Found: DELETE /mydb/mydoc
+
+When the document exists, a :exc:`Conflict` exception is raised if you don't
+supply the *rev* keyword argument.
+
+For example, we'll create a document:
+
+>>> mydoc = {'_id': 'mydoc'}
+>>> mydoc['_rev'] = db.post(mydoc)['rev']
+>>> mydoc['_rev']
+'1-967a00dff5e02add41819138abb3284d'
+
+And then try to delete it using a :class:`Server`:
+
+>>> server.delete('mydb', 'mydoc')
+Traceback (most recent call last):
+  ...
+microfiber.Conflict: 409 Conflict: DELETE /mydb/mydoc
+
+Or try deleting it using a :class:`Database`:
+
+>>> db.delete('mydoc')
+Traceback (most recent call last):
+  ...
+microfiber.Conflict: 409 Conflict: DELETE /mydb/mydoc
+
+Likewise, a :exc:`Conflict` exception is raised the *rev* you supply doesn't
 match the latest revision of the document in CouchDB (meaning the document has
 been updated since you last retrieved it).
 
-Using a :class:`Database`:
-
->>> db = Database('mydb')
->>> db.delete('mydoc', rev='2-7051cbe5c8faecd085a3fa619e6e6337')
-{'rev': '3-7379b9e515b161226c6559d90c4dc49f', 'ok': True, 'id': 'mydoc'}
-
-
-Or using a :class:`Server`:
-
->>> s = Server()
->>> s.delete('mydb', 'mydoc', rev='2-7051cbe5c8faecd085a3fa619e6e6337')
-{'rev': '3-7379b9e515b161226c6559d90c4dc49f', 'ok': True, 'id': 'mydoc'}
+For example, we'll modify "mydoc":
+
+>>> mydoc['message'] = 'hello, world'
+>>> db.post(mydoc)['rev']
+'2-91babf69deda1e2767615ba457c80807'
+
+And then try to delete the document using the outdated revision
+``'1-967a00dff5e02add41819138abb3284d'``, first using a :class:`Server`:
+
+>>> server.delete('mydb', 'mydoc', rev='1-967a00dff5e02add41819138abb3284d')
+Traceback (most recent call last):
+  ...
+microfiber.Conflict: 409 Conflict: DELETE /mydb/mydoc?rev=1-967a00dff5e02add41819138abb3284d
+
+And second using a :class:`Database`:
+
+>>> db.delete('mydoc', rev='1-967a00dff5e02add41819138abb3284d')
+Traceback (most recent call last):
+  ...
+microfiber.Conflict: 409 Conflict: DELETE /mydb/mydoc?rev=1-967a00dff5e02add41819138abb3284d
+
 
 
 Attachments
@@ -232,95 +530,178 @@
 instance, but you can do the same using a :class:`Server` instance.
 
 
-Create
-------
-
-**PUT /db/doc/attachment**
+``PUT /db/doc/att``
+-------------------
 
 You create document attachments using the :meth:`CouchBase.put_att()` method.
 
+For setup, we'll do this:
+
+>>> couch = TempCouch()
+>>> env = couch.bootstrap()
+>>> server = Server(env)
+>>> db = Database('mydb', env)
+>>> db.put(None)
+{'ok': True}
+
 If you're creating an attachment for a document that does not yet exists, the
 *rev* keyword argument isn't needed, and the document will be implicitly created
-by CouchDB.  If the document exists, you must include *rev*.
-
-A :exc:`Conflict` exception is raised if the *rev* keyword argument doesn't
-match the latest revision of the document in CouchDB (meaning the document has
-been updated since you last retrieved it).
-
-Using a :class:`Database` when the document does *not* exists:
-
->>> db = Database('mydb')
->>> db.put_att('image/png', b'PNG Data', 'mydoc', 'myatt')
-{'rev': '1-904eb7a25f6c4df64f49b0eeeb27dbbc', 'ok': True, 'id': 'mydoc'}
-
-Or using a :class:`Database` when the document does exists:
-
->>> db.put_att('image/png', b'PNG Data', 'mydoc', 'myatt2',
-...     rev='1-904eb7a25f6c4df64f49b0eeeb27dbbc'
-... )
-{'rev': '2-1e294b322cd16610bf3becb62167f7f2', 'ok': True, 'id': 'mydoc'}
-
-
-Using a :class:`Server` when the document does *not* exists:
-
->>> s = Server()
->>> s.put_att('image/png', b'PNG Data', 'mydb', 'mydoc', 'myatt')
-{'rev': '1-904eb7a25f6c4df64f49b0eeeb27dbbc', 'ok': True, 'id': 'mydoc'}
-
-Or using a :class:`Server` when the document does exists:
-
->>> s.put_att('image/png', b'PNG Data', 'mydb', 'mydoc', 'myatt2',
-...     rev='1-904eb7a25f6c4df64f49b0eeeb27dbbc'
-... )
-{'rev': '2-1e294b322cd16610bf3becb62167f7f2', 'ok': True, 'id': 'mydoc'}
-
-
-Retrieve
---------
-
-**GET /db/doc/attachment**
+by CouchDB.  For example, using a :class:`Server`:
+
+>>> server.put_att('text/plain', b'Foo', 'mydb', 'doc1', 'foo')['rev']
+'1-383671a0277edeb17918f714d1c5b63e'
+
+Or using using a :class:`Database`:
+
+>>> db.put_att('text/plain', b'Foo', 'mydb', 'doc2', 'foo')['rev']
+'1-183074fa494ac6e04d360e6354057360'
+
+If the document exists, you must provide *rev* keyword argument.  For example,
+to add a 2nd attachment to "doc1" using a :class:`Server`:
+
+>>> server.put_att('text/plain', b'Bar', 'mydb', 'doc1', 'bar', rev='1-383671a0277edeb17918f714d1c5b63e')['rev']
+'2-8654772d9053f1c949bffe3cf7ef4aa2'
+
+Or to add a 2nd attachment to "doc2" using using a :class:`Database`:
+
+>>> db.put_att('text/plain', b'Bar', 'mydb', 'doc2', 'bar', rev='1-183074fa494ac6e04d360e6354057360')['rev']
+'2-d37c9c0cedace0a2a857deed922b330e'
+
+A :exc:`Conflict` exception is raised if you don't include the *rev* keyword
+argument, of if the *rev* doesn't match the latest revision of the document in
+CouchDB (meaning the document has been updated since you last retrieved it).
+
+For example, if trying to add a 3rd attachment to "doc1" using a
+:class:`Server` and the outdated revision
+``'1-383671a0277edeb17918f714d1c5b63e'``:
+
+>>> server.put_att('text/plain', b'Baz', 'mydb', 'doc1', 'baz', rev='1-383671a0277edeb17918f714d1c5b63e')['rev']
+Traceback (most recent call last):
+  ...
+microfiber.Conflict: 409 Conflict: PUT /mydb/doc1/baz?rev=1-383671a0277edeb17918f714d1c5b63e
+
+Or if trying to add a 3rd attachment to "doc2" using a
+:class:`Database` and the outdated revision
+``'1-183074fa494ac6e04d360e6354057360'``:
+
+>>> db.put_att('text/plain', b'Baz', 'mydb', 'doc2', 'baz', rev='1-183074fa494ac6e04d360e6354057360')['rev']
+Traceback (most recent call last):
+  ...
+microfiber.Conflict: 409 Conflict: PUT /mydb/doc2/baz?rev=1-183074fa494ac6e04d360e6354057360
+
+
+``GET /db/doc/att``
+-------------------
 
 You retrieve document attachments using the :meth:`CouchBase.get_att()` method.
 
-A :exc:`NotFound` exception is raised if the attachment does not exist.
-
-Using a :class:`Database`:
-
->>> db = Database('mydb')
+For setup, we'll do this:
+
+>>> couch = TempCouch()
+>>> env = couch.bootstrap()
+>>> server = Server(env)
+>>> db = Database('mydb', env)
+>>> db.put(None)
+{'ok': True}
+>>> db.post({'_id': 'mydoc'})['rev']
+'1-967a00dff5e02add41819138abb3284d'
+
+A :exc:`NotFound` exception is raised if the attachment does not exist.  For
+example, using a :class:`Server`:
+
+>>> server.get('mydb', 'mydoc', 'myatt')
+Traceback (most recent call last):
+  ...
+microfiber.NotFound: 404 Object Not Found: GET /mydb/mydoc/myatt
+
+Or using a :class:`Database`:
+
+>>> db.get('mydoc', 'myatt')
+Traceback (most recent call last):
+  ...
+microfiber.NotFound: 404 Object Not Found: GET /mydb/mydoc/myatt
+
+Finally, we'll create an attachment with this setup:
+
+>>> db.put_att('text/plain', b'hello, world', 'mydoc', 'myatt', rev='1-967a00dff5e02add41819138abb3284d')['rev']
+'2-d403ee4d0528a7be93cffb89c4beb3e4'
+
+For example, we'll retrieve this attachment using a :class:`Server`:
+
+>>> server.get_att('mydb', 'mydoc', 'myatt')
+Attachment(content_type='text/plain', data=b'hello, world')
+
+Or using :class:`Database`:
+
 >>> db.get_att('mydoc', 'myatt')
-('image/png', b'PNG Data')
-
-
-Or using a :class:`Server`:
-
->>> s = Server()
->>> s.get_att('mydb', 'mydoc', 'myatt')
-('image/png', b'PNG Data')
-
-
-Delete
-------
-
-**DELETE /db/doc/attachment**
-
-A :exc:`NotFound` exception is raised if the attachment does not exist.
-
-A :exc:`Conflict` exception is raised if the *rev* keyword argument doesn't
-match the latest revision of the document in CouchDB (meaning the document has
-been updated since you last retrieved it).
-
-Using a :class:`Database`:
-
->>> db = Database('mydb')
->>> db.delete('mydoc', 'myatt', rev='2-1e294b322cd16610bf3becb62167f7f2')
-{'rev': '3-6de76b26d1b5a1ca533d94039132e594', 'ok': True, 'id': 'mydoc'}
-
-
-Or using a :class:`Server`:
-
->>> s = Server()
->>> s.delete('mydb', 'mydoc', 'myatt', rev='2-1e294b322cd16610bf3becb62167f7f2')
-{'rev': '3-6de76b26d1b5a1ca533d94039132e594', 'ok': True, 'id': 'mydoc'}
+Attachment(content_type='text/plain', data=b'hello, world')
+
+
+``DELETE /db/doc/att``
+----------------------
+
+For setup, we'll do this:
+
+>>> couch = TempCouch()
+>>> env = couch.bootstrap()
+>>> server = Server(env)
+>>> db = Database('mydb', env)
+>>> db.put(None)
+{'ok': True}
+>>> db.post({'_id': 'mydoc'})['rev']
+'1-967a00dff5e02add41819138abb3284d'
+
+And then add an attachment using a :class:`Server`:
+
+>>> server.put_att('text/plain', b'hello, world', 'mydb', 'mydoc', 'att1', rev='1-967a00dff5e02add41819138abb3284d')['rev']
+'2-f2d88125f27039a1af069b76c398d21e'
+
+And then add an attachment using a :class:`Database`:
+
+>>> db.put_att('text/plain', b'hello, naughty nurse', 'mydoc', 'att2', rev='2-f2d88125f27039a1af069b76c398d21e')['rev']
+'3-00d0d01ee1cc715522f060ea49e4df22'
+
+A :exc:`Conflict` exception is raised if the *rev* keyword argument isn't
+provided, for example:
+
+>>> server.delete('mydb', 'mydoc', 'att1')
+Traceback (most recent call last):
+  ...
+microfiber.Conflict: 409 Conflict: DELETE /mydb/mydoc/att1
+
+Or using :class:`Database`:
+
+>>> db.delete('mydoc', 'att1')
+Traceback (most recent call last):
+  ...
+microfiber.Conflict: 409 Conflict: DELETE /mydb/mydoc/att1
+
+Likewise, a :exc:`Conflict` exception is raised if the *rev* keyword argument
+doesn't match the latest revision of the document in CouchDB (meaning the 
+document has been updated since you last retrieved it):
+
+>>> server.delete('mydb', 'mydoc', 'att1', rev='2-f2d88125f27039a1af069b76c398d21e')
+Traceback (most recent call last):
+  ...
+microfiber.Conflict: 409 Conflict: DELETE /mydb/mydoc/att1
+
+Or using :class:`Database`:
+
+>>> db.delete('mydoc', 'att1', rev='2-f2d88125f27039a1af069b76c398d21e')
+Traceback (most recent call last):
+  ...
+microfiber.Conflict: 409 Conflict: DELETE /mydb/mydoc/att1
+
+Finally, two examples in which the attachment is deleted:
+
+>>> server.delete('mydb', 'mydoc', 'att1', rev='3-00d0d01ee1cc715522f060ea49e4df22')['rev']
+'4-b3726f26cdcf3c7101e14ca0caf701f0'
+
+Or using :class:`Database`:
+
+>>> db.delete('mydoc', 'att2', rev='4-b3726f26cdcf3c7101e14ca0caf701f0')['rev']
+'5-aca674de3a1607e3003e5d4e7c0337d6'
+
 
 
 Server
@@ -328,33 +709,44 @@
 
 To perform server-level actions, you must use a :class:`Server` instance.
 
-
-Welcome
--------
-
-**GET /**
-
-This will retrieve the CouchDB welcome response, which includes the CouchDB
-version.
-
->>> s = Server()
->>> s.get()
-{'couchdb': 'Welcome', 'version': '1.1.0'}
-
-
-Databases
+Setup for the examples:
+
+>>> couch = TempCouch()
+>>> env = couch.bootstrap()
+>>> s = Server(env)
+
+
+``GET /``
 ---------
 
-**GET /_all_dbs**
-
-This will retrieve the list of databases in this CouchDB instance.
-
->>> s.get('_all_dbs')
-['_replicator', '_users', 'dmedia', 'mydb']
-
-
-
-
-
-
+This will retrieve a ``dict`` containing the CouchDB welcome response, which
+will include the CouchDB version and other useful info.
+
+>>> sorted(s.get())
+['couchdb', 'uuid', 'vendor', 'version']
+
+
+``GET /_all_dbs``
+-----------------
+
+This will retrieve the list of databases in this CouchDB instance.  For example,
+when no user-created databases exists:
+
+>>> s.get('_all_dbs')
+['_replicator', '_users']
+
+And now if we create a database:
+
+>>> s.put(None, 'foo')
+{'ok': True}
+>>> s.get('_all_dbs')
+['_replicator', '_users', 'foo']
+
+And finally if we create another database (note the database names are returned
+in sorted order):
+
+>>> s.put(None, 'bar')
+{'ok': True}
+>>> s.get('_all_dbs')
+['_replicator', '_users', 'bar', 'foo']
 

=== modified file 'doc/microfiber.rst'
--- doc/microfiber.rst	2012-09-22 12:46:46 +0000
+++ doc/microfiber.rst	2014-02-23 01:42:08 +0000
@@ -5,21 +5,47 @@
 .. py:module:: microfiber
     :synopsis: fabric for a lightweight couch
 
-In a nutshell, the Microfiber API is the CouchDB API, nothing more.  For
-example:
+In a nutshell, Microfiber is generic REST adapter that allows you to make
+requests to an arbitrary JSON-centric REST API like CouchDB.  This means that by
+and large the Microfiber API *is*  `CouchDB REST API`_, as expressed through the
+Microfiber REST adapter.
+
+In all our examples, we'll create throw-away CouchDB instances using
+`UserCouch`_.
+
+First, well create a ``TempCouch``, and bootstrap it get the *env* we'll pass to
+a :class:`Server` or :class:`Database`.
+
+>>> from usercouch.misc import TempCouch
+>>> couch = TempCouch()
+>>> env = couch.bootstrap()
+
+A :class:`Server` expose the REST API relative to the root URL.  For example:
+
+>>> from microfiber import Server
+>>> server = Server(env)
+>>> server.get()['couchdb']  # GET /
+'Welcome'
+>>> server.put(None, 'mydb')  # PUT /mydb
+{'ok': True}
+>>> doc = {'_id': 'mydoc'}
+>>> doc['_rev'] = server.post(doc, 'mydb')['rev']  # POST /mydb
+>>> server.get('mydb', 'mydoc') == doc  # GET /mydb/mydoc
+True
+
+A :class:`Database` expose the exact same REST API relative to the root URL.
+For example:
 
 >>> from microfiber import Database
->>> db = Database('foo')
->>> db.put(None)  # PUT /foo
-{'ok': True}
->>> db.put({}, 'bar')  # PUT /foo/bar
-{'rev': '1-967a00dff5e02add41819138abb3284d', 'ok': True, 'id': 'bar'}
->>> db.get('bar')  # GET /foo/bar
-{'_rev': '1-967a00dff5e02add41819138abb3284d', '_id': 'bar'}
->>> db.delete('bar', rev='1-967a00dff5e02add41819138abb3284d')  # DELETE /foo/bar
-{'rev': '2-eec205a9d413992850a6e32678485900', 'ok': True, 'id': 'bar'}
->>> db.delete()  # DELETE /foo
-{'ok': True}
+>>> db = Database('mydb', env)
+>>> db.get()['db_name']  # GET /mydb
+'mydb'
+>>> db.put(None)  # PUT /mydb ('mydb' already exists!)
+Traceback (most recent call last):
+  ...
+microfiber.PreconditionFailed: 412 Precondition Failed: PUT /mydb/
+>>> db.get('mydoc') == doc  # GET /mydb/mydoc
+True
 
 Chances are you'll use the :class:`Database` class most of all.
 
@@ -131,7 +157,7 @@
 ...     'url': 'https://example.com/',
 ...     'ssl': {
 ...         'ca_file': '/trusted/server.ca',
-...         'ca_path': 'trusted/ca.directory/',
+...         'ca_path': '/trusted/ca.directory/',
 ...         'check_hostname': False,
 ...         'cert_file': '/my/client.cert',
 ...         'key_file': '/my/client.key',
@@ -181,10 +207,18 @@
     * :meth:`CouchBase.delete()`
     * :meth:`CouchBase.put_att()`
     * :meth:`CouchBase.get_att()`
-    
+
 All these methods are inherited unchanged by the :class:`Server` and
 :class:`Database` classes.
 
+All the method examples below assume this setup:
+
+>>> from usercouch.misc import TempCouch
+>>> from microfiber import CouchBase, dumps
+>>> couch = TempCouch()
+>>> env = couch.bootstrap()
+
+
 .. class:: CouchBase(env='http://localhost:5984/')
 
 
@@ -192,50 +226,59 @@
     
         PUT *obj*.
 
-        For example, to create the database "foo":
+        For example, to create the database "db1":
 
-        >>> cb = CouchBase()
-        >>> cb.put(None, 'foo')  #doctest: +SKIP
+        >>> cb = CouchBase(env)
+        >>> cb.put(None, 'db1')
         {'ok': True}
 
-        Or to create the doc "baz" in the database "foo":
+        Or to create the doc "doc1" in the database "db1":
 
-        >>> cb.put({'micro': 'fiber'}, 'foo', 'baz')  #doctest: +SKIP
-        {'rev': '1-fae0708c46b4a6c9c497c3a687170ad6', 'ok': True, 'id': 'bar'}
+        >>> cb.put({'micro': 'fiber'}, 'db1', 'doc1')['rev']
+        '1-fae0708c46b4a6c9c497c3a687170ad6'
 
 
     .. method:: post(obj, *parts, **options)
-    
+
         POST *obj*.
 
-        For example, to create the doc "bar" in the database "foo":
-
-        >>> cb = CouchBase()
-        >>> cb.post({'_id': 'bar'}, 'foo')  #doctest: +SKIP
-        {'rev': '1-967a00dff5e02add41819138abb3284d', 'ok': True, 'id': 'bar'}
-
-        Or to compact the database "foo":
-
-        >>> cb.post(None, 'foo', '_compact')  #doctest: +SKIP
-        {'ok': True}
-    
-    
+        For example, to create the doc "doc2" in the database "db2", we'll first
+        create "db2":
+
+        >>> cb = CouchBase(env)
+        >>> cb.put(None, "db2")
+        {'ok': True}
+
+        And now we'll save the "doc2" document:
+
+        >>> cb.post({'_id': 'doc2'}, 'db2')['rev']
+        '1-967a00dff5e02add41819138abb3284d'
+
+        Or to compact the database "db2":
+
+        >>> cb.post(None, 'db2', '_compact')
+        {'ok': True}
+
+
     .. method:: get(*parts, **options)
     
         Make a GET request.
 
         For example, to get the welcome info from CouchDB:
 
-        >>> cb = CouchBase()
-        >>> cb.get()  #doctest: +SKIP
-        {'couchdb': 'Welcome', 'version': '1.1.0'}
-
-        Or to request the doc "bar" from the database "foo", including any
-        attachments:
-
-        >>> cb.get('foo', 'bar', attachments=True)  #doctest: +SKIP
-        {'_rev': '1-967a00dff5e02add41819138abb3284d', '_id': 'bar'}
-
+        >>> cb = CouchBase(env)
+        >>> cb.get()['couchdb']
+        'Welcome'
+
+        Or to request the doc "db1" from the database "doc1":
+
+        >>> doc = cb.get('db1', 'doc1')
+        >>> print(dumps(doc, pretty=True))
+        {
+            "_id": "doc1",
+            "_rev": "1-fae0708c46b4a6c9c497c3a687170ad6",
+            "micro": "fiber"
+        }
 
     .. method:: head(*parts, **options)
     
@@ -243,28 +286,28 @@
 
         Returns a ``dict`` containing the response headers from the HEAD
         request.
-        
-        For example, to make a HEAD request on the doc "bar" in the database
-        "foo":
-        
-        >>> cb = CouchBase()
-        >>> cb.head('foo', 'baz')['Etag']  #doctest: +SKIP
-        '"1-967a00dff5e02add41819138abb3284d"'
+
+        For example, to make a HEAD request on the doc "doc1" in the database
+        "db1":
+
+        >>> cb = CouchBase(env)
+        >>> cb.head('db1', 'doc1')['etag']
+        '"1-fae0708c46b4a6c9c497c3a687170ad6"'
 
 
     .. method:: delete(*parts, **options)
     
         Make a DELETE request.
 
-        For example, to delete the doc "bar" in the database "foo":
-
-        >>> cb = CouchBase()
-        >>> cb.delete('foo', 'bar', rev='1-967a00dff5e02add41819138abb3284d')  #doctest: +SKIP
-        {'rev': '1-967a00dff5e02add41819138abb3284d', 'ok': True, 'id': 'bar'}
-
-        Or to delete the database "foo":
-
-        >>> cb.delete('foo')  #doctest: +SKIP
+        For example, to delete the doc "doc2" in the database "db2":
+
+        >>> cb = CouchBase(env)
+        >>> cb.delete('db2', 'doc2', rev='1-967a00dff5e02add41819138abb3284d')['rev']
+        '2-eec205a9d413992850a6e32678485900'
+
+        Or two delete the "db2" database:
+
+        >>> cb.delete('db2')
         {'ok': True}
 
 
@@ -272,30 +315,40 @@
     
         PUT an attachment.
 
-        For example, to upload the attachment "baz" for the doc "bar" in the
-        database "foo":
-
-        >>> cb = CouchBase()
-        >>> cb.put_att('image/png', b'da pic', 'foo', 'bar', 'baz')  #doctest: +SKIP
-        {'rev': '1-d536771b631a30c2ab4c0340adc72570', 'ok': True, 'id': 'bar'}
+        If uploading an attachment for a document that already exist, you don't
+        need to specify the *rev*.  For example, to upload the attachment "att1"
+        for the doc "doc1" in the database "db1".
+
+        >>> cb = CouchBase(env)
+        >>> cb.put_att('text/plain', b'hello, world', 'db1', 'doc1', 'att1',
+        ...     rev='1-fae0708c46b4a6c9c497c3a687170ad6',
+        ... )['rev']
+        '2-bd4ac0c5ca963e5b4f0f3b09ea540de2'
+
+        On the other hand, if uploading an attachment for a doc that doesn't
+        exist yet, you don't need to specify the *rev*.  For example, to upload
+        the attachment "newatt" for the doc "newdoc" in "db":
+
+        >>> cb.put_att('text/plain', b'New', 'db1', 'newdoc', 'newatt')['rev']
+        '1-b2c33fbf19cadc92ab7b9860e116bb25'
 
         Note that you don't need any attachment-specific method for DELETE. 
         Just use :meth:`CouchBase.delete()`, like this:
-        
-        >>> cb.delete('foo', 'bar', 'baz', rev='1-d536771b631a30c2ab4c0340adc72570')  #doctest: +SKIP
-        {'rev': '2-082e66867f6d4d1753d7d0bf08122425', 'ok': True, 'id': 'bar'}
-
-        
+
+        >>> cb.delete('db1', 'newdoc', 'newatt', rev='1-b2c33fbf19cadc92ab7b9860e116bb25')['rev']
+        '2-5a5ecda09b7010bc3f190d8766398cff'
+
+
     .. method:: get_att(*parts, **options)
     
         GET an attachment.
 
         Returns a ``(content_type, data)`` tuple.  For example, to download the
-        attachment "baz" for the doc "bar" in the database "foo":
+        attachment "att1" for the doc "doc1" in the database "db1":
 
-        >>> cb = CouchBase()
-        >>> cb.get_att('foo', 'bar', 'baz')  #doctest: +SKIP
-        ('image/png', b'da pic')
+        >>> cb = CouchBase(env)
+        >>> cb.get_att('db1', 'doc1', 'att1')
+        Attachment(content_type='text/plain', data=b'hello, world')
 
 
 
@@ -540,6 +593,7 @@
 
     For example:
 
+    >>> from microfiber import dumps
     >>> doc = {
     ...     'hello': 'мир',
     ...     'welcome': 'все',
@@ -549,8 +603,9 @@
 
     Whereas if you directly call ``json.dumps()`` without *ensure_ascii=False*:
 
+    >>> import json
     >>> json.dumps(doc, sort_keys=True)
-    '{"hello": "\\\\u043c\\\\u0438\\\\u0440", "welcome": "\\\\u0432\\\\u0441\\\\u0435"}'
+    '{"hello": "\\u043c\\u0438\\u0440", "welcome": "\\u0432\\u0441\\u0435"}'
 
     By default compact encoding is used, but if you supply *pretty=True*,
     4-space indentation will be used:
@@ -562,18 +617,6 @@
     }
 
 
-.. function:: dc3_env()
-
-    Return the dc3 environment information.
-
-    For example, to create a :class:`Database` with the correct per-user `dc3`_
-    environment:
-
-    >>> from microfiber import dc3_env, Database
-    >>> db = Database('dmedia-0', dc3_env())
-    >>> db.url
-    'http://localhost:41289/'
-
 
 .. function:: dmedia_env()
 
@@ -583,9 +626,7 @@
     `Dmedia`_ environment:
 
     >>> from microfiber import dmedia_env, Database
-    >>> db = Database('dmedia-0', dmedia_env())
-    >>> db.url
-    'http://localhost:41289/'
+    >>> db = Database('dmedia-1', dmedia_env())  #doctest: +SKIP 
 
     If you're using Microfiber to work with `Dmedia`_ or `Novacut`_, please use
     this function instead of :func:`dc3_env()` as starting with the Dmedia 12.01
@@ -697,9 +738,9 @@
         The exact return value from the CouchDB request.
 
 
-
 .. _`Novacut`: https://wiki.ubuntu.com/Novacut
 .. _`UserCouch`: https://launchpad.net/usercouch
+.. _`CouchDB REST API`: http://couchdb.readthedocs.org/en/latest/api/index.html
 .. _`dc3`: https://launchpad.net/dc3
 .. _`Dmedia`: https://launchpad.net/dmedia
 .. _`python-couchdb`: http://packages.python.org/CouchDB/client.html#database

=== modified file 'setup.py'
--- setup.py	2013-02-20 23:00:54 +0000
+++ setup.py	2014-02-23 01:42:08 +0000
@@ -36,11 +36,25 @@
 from distutils.core import setup
 from distutils.cmd import Command
 import os
+from os import path
+import subprocess
 
 import microfiber
 from microfiber.tests.run import run_tests
 
 
+def run_sphinx_doctest():
+    sphinx_build = '/usr/share/sphinx/scripts/python3/sphinx-build'
+    if not os.access(sphinx_build, os.R_OK | os.X_OK):
+        print('warning, cannot read and execute: {!r}'.format(sphinx_build))
+        return
+    tree = path.dirname(path.abspath(__file__))
+    doc = path.join(tree, 'doc')
+    doctest = path.join(tree, 'doc', '_build', 'doctest')
+    cmd = [sys.executable, sphinx_build, '-EW', '-b', 'doctest', doc, doctest]
+    subprocess.check_call(cmd)
+
+
 class Test(Command):
     description = 'run unit tests and doc tests'
 
@@ -63,6 +77,7 @@
             os.environ['MICROFIBER_TEST_SKIP_SLOW'] = 'true'
         if not run_tests():
             raise SystemExit('2')
+        run_sphinx_doctest()
 
 
 setup(