Merge lp:~jderose/usercouch/docs into lp:usercouch

[Jason Gerard DeRose]

Adds a first pass at sphinx documentation. The API docs are a bit rough still, but I think the tutorial is in good shape and can quickly get newcomers productive.

[James Raymond (jamesmr)]

review: Approve

=== added file '.bzrignore'
--- .bzrignore	1970-01-01 00:00:00 +0000
+++ .bzrignore	2012-08-21 03:50:43 +0000
@@ -0,0 +1,1 @@
+_build

=== modified file 'debian/control'
--- debian/control	2012-08-13 09:16:29 +0000
+++ debian/control	2012-08-21 03:50:43 +0000
@@ -4,6 +4,7 @@
 Maintainer: Jason Gerard DeRose <[e-mail]>
 Build-Depends: debhelper (>= 9),
     python3-all (>= 3.2),
+    python3-sphinx (>= 1.1),
     couchdb-bin (>= 1.2.0)
 Standards-Version: 3.9.3
 X-Python3-Version: >= 3.2
@@ -12,7 +13,7 @@
 Package: python3-usercouch
 Architecture: all
 Depends: ${python3:Depends}, ${misc:Depends}, couchdb-bin (>= 1.2.0)    
-Suggests: python3-microfiber
+Suggests: python3-microfiber, python3-usercouch-doc
 Description: starts per-user CouchDB instances for fun, profit, unit testing
  UserCouch is a Python3 library for starting per-user CouchDB instances,
  including throw-away instances for unit testing. It's easy:
@@ -21,8 +22,28 @@
  from microfiber import Database
  tmp = TempCouch()
  env = tmp.bootstrap()
- db = Database('example', env)
- db.put(None) # Create the database
- db.post({'_id': 'foo'}) # Create a document
- .
- Also see Microfiber: https://launchpad.net/microfiber
+ db = Database('mydb', env)
+ db.put(None)  # Create the database
+ db.post({'_id': 'mydoc'})  # Create a document
+ .
+ Also see Microfiber: https://launchpad.net/microfiber
+
+Package: python3-usercouch-doc
+Architecture: all
+Section: doc
+Depends: ${sphinxdoc:Depends}, ${misc:Depends}
+Suggests: python3-usercouch
+Description: documentation for python3-usercouch
+ UserCouch is a Python3 library for starting per-user CouchDB instances,
+ including throw-away instances for unit testing. It's easy:
+ .
+ from usercouch.misc import TempCouch
+ from microfiber import Database
+ tmp = TempCouch()
+ env = tmp.bootstrap()
+ db = Database('mydb', env)
+ db.put(None)  # Create the database
+ db.post({'_id': 'mydoc'})  # Create a document
+ .
+ Also see Microfiber: https://launchpad.net/microfiber
+

=== added file 'debian/python3-usercouch-doc.doc-base'
--- debian/python3-usercouch-doc.doc-base	1970-01-01 00:00:00 +0000
+++ debian/python3-usercouch-doc.doc-base	2012-08-21 03:50:43 +0000
@@ -0,0 +1,8 @@
+Document: usercouch
+Title: UserCouch documentation
+Abstract: Documentation for UserCouch.
+Section: Programming
+
+Format: HTML
+Index: /usr/share/doc/python3-usercouch-doc/html/index.html
+Files: /usr/share/doc/python3-usercouch-doc/html/*.html

=== added file 'debian/python3-usercouch-doc.install'
--- debian/python3-usercouch-doc.install	1970-01-01 00:00:00 +0000
+++ debian/python3-usercouch-doc.install	2012-08-21 03:50:43 +0000
@@ -0,0 +1,1 @@
+doc/_build/html/* usr/share/doc/python3-usercouch-doc/html

=== modified file 'debian/rules'
--- debian/rules	2012-08-13 09:14:59 +0000
+++ debian/rules	2012-08-21 03:50:43 +0000
@@ -1,22 +1,23 @@
 #!/usr/bin/make -f
 
-PYTHON3=$(shell py3versions -vr)
-
 %:
-	dh $@ --with=python3
-
-test-python%:
-	python$* setup.py test
+	dh $@ --with=python3 --with=sphinxdoc
 
 override_dh_auto_clean:
-	rm -rf build/
+	rm -rf build/ doc/_build/
 
 override_dh_auto_build:
+	sphinx-build -b html doc/ doc/_build/html/
 	set -ex; for python in $(shell py3versions -r); do \
 		$$python setup.py build \
 				--executable=/usr/bin/python3; \
 	done
 
+override_dh_auto_test:
+	set -ex; for python in $(shell py3versions -r); do \
+		$$python setup.py test; \
+	done
+
 override_dh_auto_install:
 	set -ex; for python in $(shell py3versions -r); do \
 		$$python setup.py install \
@@ -24,4 +25,3 @@
 				--root=$(CURDIR)/debian/python3-usercouch; \
 	done
 
-override_dh_auto_test: $(PYTHON3:%=test-python%)

=== added directory 'doc'
=== added file 'doc/Makefile'
--- doc/Makefile	1970-01-01 00:00:00 +0000
+++ doc/Makefile	2012-08-21 03:50:43 +0000
@@ -0,0 +1,153 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/UserCouch.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/UserCouch.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/UserCouch"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/UserCouch"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."

=== added directory 'doc/_static'
=== added directory 'doc/_templates'
=== added file 'doc/conf.py'
--- doc/conf.py	1970-01-01 00:00:00 +0000
+++ doc/conf.py	2012-08-21 03:50:43 +0000
@@ -0,0 +1,35 @@
+import sys
+from os import path
+
+tree = path.dirname(path.dirname(path.abspath(__file__)))
+sys.path.insert(0, tree)
+
+import usercouch
+
+
+# Project info
+project = 'UserCouch'
+copyright = '2012, Novacut Inc'
+version = usercouch.__version__[:5]
+release = usercouch.__version__
+
+
+# General config
+needs_sphinx = '1.1'
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.coverage',
+]
+templates_path = ['_templates']
+source_suffix = '.rst'
+master_doc = 'index'
+exclude_patterns = ['_build']
+pygments_style = 'sphinx'
+
+
+# HTML config
+html_theme = 'default'
+html_static_path = ['_static']
+htmlhelp_basename = 'UserCouchdoc'
+

=== added file 'doc/index.rst'
--- doc/index.rst	1970-01-01 00:00:00 +0000
+++ doc/index.rst	2012-08-21 03:50:43 +0000
@@ -0,0 +1,49 @@
+UserCouch
+=========
+
+`UserCouch`_ is a Python3 library for starting per-user `CouchDB`_ instances,
+including throw-away instances for unit testing.  It's especially easy to use
+with `Microfiber`_, for example:
+
+>>> from usercouch.misc import TempCouch
+>>> from microfiber import Database
+>>> tmpcouch = TempCouch()
+>>> env = tmpcouch.bootstrap()
+>>> db = Database('mydb', env)
+>>> db.put(None)  # Create the database
+{'ok': True}
+>>> db.post({'_id': 'mydoc'})  # Create a document
+{'rev': '1-967a00dff5e02add41819138abb3284d', 'ok': True, 'id': 'mydoc'}
+
+UserCouch is being developed as part of the `Novacut`_ project.  UserCouch
+packages are available for Ubuntu in the `Novacut Stable Releases PPA`_ and the
+`Novacut Daily Builds PPA`_.
+
+If you have questions or need help getting started with UserCouch, please stop
+by the `#novacut`_ IRC channel on freenode.
+
+UserCouch is licensed `LGPLv3+`_.
+
+
+Contents:
+
+.. toctree::
+    :maxdepth: 2
+
+    tutorial
+    usercouch
+    usercouch_misc
+
+
+
+.. _`UserCouch`: https://launchpad.net/usercouch
+.. _`CouchDB`: http://couchdb.apache.org/
+.. _`Microfiber`: https://launchpad.net/microfiber
+.. _`LGPLv3+`: http://www.gnu.org/licenses/lgpl-3.0.html
+
+
+.. _`Novacut`: https://wiki.ubuntu.com/Novacut
+.. _`Novacut Stable Releases PPA`: https://launchpad.net/~novacut/+archive/stable
+.. _`Novacut Daily Builds PPA`: https://launchpad.net/~novacut/+archive/daily
+.. _`#novacut`: http://webchat.freenode.net/?channels=novacut
+

=== added file 'doc/tutorial.rst'
--- doc/tutorial.rst	1970-01-01 00:00:00 +0000
+++ doc/tutorial.rst	2012-08-21 03:50:43 +0000
@@ -0,0 +1,154 @@
+UserCouch Tutorial
+==================
+
+.. py:currentmodule:: usercouch
+
+To create a :class:`UserCouch` instance, you must supply the *basedir*
+directory in which all the `CouchDB`_ data will be stored.  For example:
+
+>>> from usercouch import UserCouch
+>>> mycouch = UserCouch('/home/jderose/.usercouch')
+
+Then  call :meth:`UserCouch.bootstrap()` to create the one-time configuration
+and start CouchDB:
+
+>>> env = mycouch.bootstrap()
+
+The returned *env* will be a ``dict`` with an extensible environment
+following the same conventions as `Microfiber`_.
+
+Because this is a per-user CouchDB instance, a random port is chosen when you
+call :meth:`UserCouch.bootstrap()`, and *env* will contain this port:
+
+>>> env['port']
+53206
+
+The *env* also contains the HTTP URL of the CouchDB instance:
+
+>>> env['url']
+'http://localhost:53206/'
+
+By default, :meth:`UserCouch.bootstrap()` will configure CouchDB for basic
+HTTP auth, using a random username and password each time:
+
+>>> env['basic']
+{'username': '72UT4WBTH3HFGT4S5OMYXGWA', 'password': 'WP5DUTBRQRYXFYKGZQ4MPDHB'}
+
+Normally the CouchDB process will be automatically killed for you when the
+:class:`UserCouch` instance is garbage collected.  However, in certain
+circumstances, you may need to manually call :meth:`UserCouch.kill()`.
+
+
+
+Bootstrap Options
+-----------------
+
+The :meth:`UserCouch.bootstrap()` *auth* kwarg can be ``'open'``, ``'basic'``,
+or ``'oauth'``.  As noted above, it defaults to ``'basic'``.
+
+If you use ``auth='open'``, you'll get an *env* similar to this:
+
+>>> {
+...     'port': 41505,
+...     'url': 'http://localhost:41505/',
+... }
+
+If you use ``auth='basic'``, you'll get an *env* similar to this:
+
+>>> {
+...     'port': 57910,
+...     'url': 'http://localhost:57910/',
+...     'basic': {
+...         'username': 'BKBTG7MX5Z6CTWHBOBXOX63S',
+...         'password': 'YGQQRSDMIF6GTZ6JMETWPUUE',
+...     },
+... }
+
+If you use ``auth='oauth'``, you'll get an *env* similar to this:
+
+>>> {
+...     'port': 56618
+...     'url': 'http://localhost:56618/', 
+...     'basic': {
+...         'username': 'MAO5VQIKCJWS7NGGMV2IYC7S',
+...         'password': 'A7RDFDAMUFFFBP72VWSGK5QD',
+...     },
+...     'oauth': {
+...         'consumer_key': 'MDWS6LVY4N7TSBKCNW4UWMVW',
+...         'consumer_secret': 'DA2TGMAUTRASC67ZZPVJAXYY',
+...         'token': 'PU7WWZNC3RJDX3CAOW3Q6TZW',
+...         'token_secret': 'H7XPTS2QHKYFQ4Z35NSKF3FR',
+...     },
+... }
+
+
+
+The Lockfile
+------------
+
+The :class:`UserCouch` instance will store all the CouchDB data within the
+*basedir* you provide.  To prevent multiple :class:`UserCouch` instances from
+starting multiple CouchDB instances pointing at the same database files, a
+lockfile is used.
+
+If the lock cannot be aquired, a :exc:`LockError` is raised:
+
+>>> mycouch2 = UserCouch('/home/jderose/.usercouch')
+Traceback (most recent call last):
+  ...
+usercouch.LockError: cannot acquire exclusive lock on '/home/jderose/.usercouch/lockfile'
+
+Note that it's perfectly fine for multiple :class:`UserCouch` instances to be running
+simultaneously as long as each uses its own *basedir*.
+
+
+
+Unit Testing
+------------
+
+.. py:currentmodule:: usercouch.misc
+
+When unit testing or experimenting with CouchDB, it's handy to have throw-away
+CouchDB instances.  That way your tests start with CouchDB in a known state,
+plus you can't accidentally hose your production data.
+
+The :mod:`usercouch.misc` module contains two classes aimed at unit testing.
+
+The first is the :class:`TempCouch` class, which you can use like this:
+
+>>> from usercouch.misc import TempCouch
+>>> tmpcouch = TempCouch()
+>>> env = tmpcouch.bootstrap()
+
+:class:`TempCouch` is a :class:`usercouch.UserCouch` subclass that creates a
+one-time temporary directory to be used as the *basedir*.  When the
+:class:`TempCouch` instance is garbage collected, this temporary directory
+(and any files it contains) are automatically deleted.
+
+The second is the :class:`CouchTestCase` class.  It's a ``unittest.TestCase``
+subclass with ``setUp()`` and ``tearDown()`` methods that create and destroy
+a :class:`TempCouch` instance for each test.
+
+The typical :class:`CouchTestCase` pattern looks like this:
+
+>>> from usercouch.misc import CouchTestCase
+>>> from microfiber import Database
+>>>
+>>> class TestFoo(CouchTestCase):
+...     def test_bar(self):
+...         db = Database('mydb', self.env)
+...         self.assertEqual(db.put(None), {'ok': True})
+... 
+...     def test_baz(self):
+...         db = Database('mydb', self.env)
+...         self.assertEqual(db.put(None), {'ok': True})
+...
+
+Because a new :class:`TempCouch` is created by ``setUp()`` prior to running
+each test method, both the ``test_bar()`` and ``test_baz()`` tests will pass.
+
+
+
+.. _`Microfiber`: https://launchpad.net/microfiber
+.. _`CouchDB`: http://couchdb.apache.org/
+

=== added file 'doc/usercouch.rst'
--- doc/usercouch.rst	1970-01-01 00:00:00 +0000
+++ doc/usercouch.rst	2012-08-21 03:50:43 +0000
@@ -0,0 +1,127 @@
+:mod:`usercouch` API Reference
+==============================
+
+.. py:module:: usercouch
+    :synopsis: Start per-user CouchDB instances for fun, profit, unit testing
+
+
+Exceptions
+----------
+
+.. exception:: LockError(lockfile)
+
+    Raised when lock cannot be acquired when creating a :class:`UserCouch`.
+
+    .. attribute:: lockfile
+
+        The path of the lockfile
+
+
+
+:class:`UserCouch` class
+------------------------
+
+.. class:: UserCouch(basedir)
+
+    Starts a per-user CouchDB instance.
+
+    For example:
+
+    >>> mycouch = UserCouch('/home/jderose/.usercouch')
+    >>> env = mycouch.bootstrap()
+
+    .. attribute:: basedir
+
+        The directory provided when instance was created.
+
+    .. method:: bootstrap(auth='basic', overrides=None)
+
+        Create the one-time configuration and start CouchDB.
+        
+        *auth* must be ``'open'``, ``'basic'``, or ``'oauth'``.
+
+        The return value is an *env* dictionary that follows the
+        `Microfiber`_ conventions.
+
+    .. method:: start()
+
+        Start (or re-start) CouchDB.
+
+    .. method:: kill()
+
+        Kill the CouchDB process.
+
+        Normally this method will be called automatically when the
+        :class:`UserCouch` instance is garbage collected, but in certain
+        circumstances you may need to explicitly call it.
+
+    .. method:: isalive()
+
+        Make an HTTP request to see if the CouchDB server is alive.
+
+    .. method:: check()
+    
+        Test if the CouchDB server is alive, restart it if not.
+
+    .. method:: crash()
+
+        Terminate the CouchDB process to simulate a CouchDB crash.
+
+
+
+Helper functions
+----------------
+
+.. function:: random_b32(numbytes=15)
+
+    Return a random 120-bit base32-encoded random string.
+
+    The ``str`` will be 24-characters long, URL and file-system safe.  For
+    example:
+
+    >>> random_b32()
+    '6NOLCDV3EQCPJDL43STIZIHN'
+
+
+.. function:: random_oauth()
+
+    Return a ``dict`` containing random OAuth 1a tokens.
+    
+    For example:
+
+    >>> random_oauth()
+    {
+        'consumer_key': 'YXOIWEJOQW4VRGNNEGT6SQYN',
+        'consumer_secret': '6KFO4Y4OZQT3YGJ4ZUYOR5I2',
+        'token': 'DADIN54ILMCASM2W6S77Q2KW',
+        'token_secret': '6T2BFYDJLES7LPFNJOFPEBQO'
+    }
+
+
+.. function:: random_salt()
+
+    Return a 128-bit hex-encoded random salt for use by :func:`couch_hashed()`.
+
+    For example:
+    
+    >>> random_salt()
+    'da52c844db4b8bd88ebb96d72542457a'
+
+
+.. function:: couch_hashed(password, salt)
+
+    Hash *password* using *salt*.
+
+    This returns a CouchDB-style hashed password to be used in the session.ini
+    file.  For example:
+
+    >>> couch_hashed('secret', 'da52c844db4b8bd88ebb96d72542457a')
+    '-hashed-ddf425840fd7f81cc45d9e9f5aa484d1f60964a9,da52c844db4b8bd88ebb96d72542457a'
+
+    Typically :class:`UserCouch` is used with a per-session random password,
+    so this function means that the clear-text of the password is only stored
+    in memory, is never written to disk.
+
+
+
+.. _`Microfiber`: https://launchpad.net/microfiber

=== added file 'doc/usercouch_misc.rst'
--- doc/usercouch_misc.rst	1970-01-01 00:00:00 +0000
+++ doc/usercouch_misc.rst	2012-08-21 03:50:43 +0000
@@ -0,0 +1,45 @@
+:mod:`usercouch.misc` API Reference
+===================================
+
+.. py:module:: usercouch.misc
+    :synopsis: Misc helpers for unit testing
+    
+The :mod:`usercouch.misc` module provides some helper classes to make it easy
+to use good CouchDB unit testing idioms.
+
+
+:class:`TempCouch` class
+------------------------
+
+.. class:: TempCouch
+
+    A throw-away CouchDB that stores files in a temporary directory.
+
+
+
+:class:`CouchTestCase` class
+-----------------------------
+
+If subclasses need to provide their own ``setUp()`` or ``tearDown()`` methods,
+be sure to call the super methods.
+
+.. class:: CouchTestCase
+
+    Base-class for CouchDB using unit tests.
+
+    .. attribute:: tmpcouch
+
+        The :class:`TempCouch` instance created by :meth:`CouchTestCase.setUp()`.
+
+    .. attribute:: env
+
+        The *env* returned by :meth:`usercouch.UserCouch.bootstrap()`.
+
+    .. method:: setUp()
+
+        Create and bootstrap a :class:`TempCouch` instance.
+
+    .. method:: tearDown()
+
+        Destroy the :class:`TempCouch` instance.
+

=== modified file 'usercouch/__init__.py'
--- usercouch/__init__.py	2012-07-15 05:41:06 +0000
+++ usercouch/__init__.py	2012-08-21 03:50:43 +0000
@@ -122,11 +122,14 @@
     Hash *password* using *salt*.
 
     This returns a CouchDB-style hashed password to be use in the session.ini
-    file.
+    file.  For example:
+
+    >>> couch_hashed('secret', 'da52c844db4b8bd88ebb96d72542457a')
+    '-hashed-ddf425840fd7f81cc45d9e9f5aa484d1f60964a9,da52c844db4b8bd88ebb96d72542457a'
 
     Typically `UserCouch` is used with a per-session random password, so this
-    function means that the clear-text of the password is only stored in memory,
-    is never written to disk.
+    function means that the clear-text of the password is only stored in
+    memory, is never written to disk.
     """
     assert len(salt) == 32
     data = (password + salt).encode('utf-8')