Run doctests on all examples in sphinx documentation

[Jason Gerard DeRose]

Documentation that doesn't get automatically tested is worthless! You can quote me on that :P

Last month I was still stumbling around figuring out how to write documentation using Sphinx, so I didn't get things setup to automatically run doctests for all the examples in the documentation. Plus I was a bit confused as to whether this was possible for Python3 modules... but after looking into things a bit more, it seems that although you can't use the `autodoc` extension for Python3 modules, you can use `doctest`.

Anyway, these docs tests will be a bit tricky as by its nature CouchDB involves a lot of random values (at the very least doc['_rev'] has a random value after the '1-', '2-', etc). So our options are:

  1) Setup the doctests to use a dummy HTTP connection that will return consistent, canned values

  2) Setup the doctests to create temporary CouchDB instances using `usercouch` and make liberal use of doctest: +ELLIPSIS

I'm leaning toward (2) personally as then we make sure the examples truly work with a real-live CouchDB.

In a related bug, we're going to start running all the live tests by default and set them up using `usercouch`:

https://bugs.launchpad.net/microfiber/+bug/862945

[Jason Gerard DeRose (jderose)]

Ah, forgot link to Sphinx documentation for doctest extension:

http://sphinx.pocoo.org/ext/doctest.html