minor documentation fixes

9 files changed, 42 insertions, 35 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 171c229..4167e36 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -30,7 +30,6 @@ sys.path.insert(0, source_root)
 #which contains some sphinx extensions used by passlib
 import cloud_sptheme
 
-
 # -- General configuration -----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
diff --git a/docs/index.rst b/docs/index.rst
index dffdfc9..97e62a6 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -12,12 +12,14 @@ It can be used for a variety of purposes:
 * encrypting & verifying most known hash formats used by:
     - Linux & BSD shadow files
     - Apache htpasswd & htdigest files
-    - MySQL, PostgreSQL, Oracle user account tables
-    - LDAP
-* drop-in password hashing for new python applications.
+    - MySQL, PostgreSQL, and Oracle user account tables
+    - LDAP style password hashes
+* drop-in password hash support for new python applications.
 * building a configurable hashing policy
   for python applications to migrate existing hashing schemes.
 
+See the library overview for usage examples.
+
 Quick Links
 ===========
 
@@ -53,4 +55,3 @@ Online Resources
 * **Downloads**:   `<http://code.google.com/p/passlib/downloads>`_
 * **PyPI**:       `<http://pypi.python.org/pypi/passlib>`_
 * **Source**:     `<http://code.google.com/p/passlib/source>`_
-
diff --git a/docs/install.rst b/docs/install.rst
index fb99468..77e7ce0 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -31,16 +31,16 @@ PassLib is pure-python, and should be useable on all platforms.
 
 Installing
 ==========
-To install from source directory using ``setup.py`` (requires Setuptools or Distribute)::
+* To install from source directory using ``setup.py`` (requires Setuptools or Distribute)::
 
    python setup.py build
    sudo python setup.py install
 
-To install using easy_install::
+* To install using easy_install::
 
    easy_install passlib
 
-To install using pip::
+* To install using pip::
 
    pip install passlib
 
@@ -59,7 +59,7 @@ Once PassLib and Nose have been installed, the tests may be run from the source
     PASSLIB_TESTS="all" nosetests -v passlib/tests
 
 ..
-    NOTE: commented this out from published manual, until astdoc package is cleaned up
+    NOTE: commented this out from published manual, until cloud theme is cleaned up
 
     Documentation
     =============
@@ -69,11 +69,9 @@ Once PassLib and Nose have been installed, the tests may be run from the source
     If you wish to generate your own copy of the documentation,
     you will need to:
 
-    * install `Sphinx <http://sphinx.pocoo.org/>`_ (1.0 or better)
-    * install `astdoc <XXX url not available yet XXX>`_ (a bundle of custom sphinx themes & extensions
-      used by Assurance Technologies).
-    * download the PassLib source
-    * run :samp:`python docs/make.py clean html`.
-
-    Once Sphinx completes it's run, point a web browser to the file at :samp:`docs/_build/html/index.html`
-    to access the PassLib documentation in html format.
+    1. install `Sphinx <http://sphinx.pocoo.org/>`_ (1.0 or better)
+    2. install the `Cloud Sphinx Theme <http://packages.python.org/cloud_sptheme>`_.
+    3. download the PassLib source
+    4. from the PassLib source directory, run :samp:`python docs/make.py clean html`.
+    5. Once Sphinx completes it's run, point a web browser to the file at :samp:`docs/_build/html/index.html`
+       to access the PassLib documentation in html format.
diff --git a/docs/lib/passlib.apps.rst b/docs/lib/passlib.apps.rst
index 1f5daec..f976afb 100644
--- a/docs/lib/passlib.apps.rst
+++ b/docs/lib/passlib.apps.rst
@@ -14,7 +14,7 @@ see the documentation for the :class:`CryptContext` class itself).
 
 Custom Applications
 ===================
-.. object:: custom_app_context
+.. data:: custom_app_context
 
     This :class:`!CryptContext` object is provided for new python applications
     to quickly and easily add password hashing support.
@@ -45,7 +45,7 @@ Custom Applications
 
 LDAP
 ====
-.. object:: ldap_context
+.. data:: ldap_context
 
     This object provides a pre-configured :class:`!CryptContext` instance
     for handling LDAPv2 password hashes. It recognizes all
@@ -70,7 +70,7 @@ MySQL
 This module provides two pre-configured :class:`!CryptContext` instances
 for handling MySQL user passwords:
 
-.. object:: mysql_context
+.. data:: mysql_context
 
     This object should recognize the new :class:`~passlib.hash.mysql41` hashes,
     as well as any legacy :class:`~passlib.hash.mysql323` hashes.
@@ -79,7 +79,7 @@ for handling MySQL user passwords:
 
     This should be used with MySQL version 4.1 and newer.
 
-.. object:: mysql3_context
+.. data:: mysql3_context
 
     This object is for use with older MySQL deploys which only recognize
     the :class:`~passlib.hash.mysql323` hash.
@@ -91,7 +91,7 @@ PHPass
 `PHPass <http://www.openwall.com/phpass/>_` is a PHP password hashing library,
 and hashes derived from it are found in a number of PHP applications.
 
-.. object:: phpass_context
+.. data:: phpass_context
 
     This object following the standard PHPass logic:
     it supports :class:`~passlib.hash.bcrypt`, :class:`~passlib.hash.bsdi_crypt`,
@@ -100,13 +100,13 @@ and hashes derived from it are found in a number of PHP applications.
     BCrypt is used as the default if support is available,
     otherwise BSDI-Crypt will be used as the default.
 
-.. object:: phpbb3_context
+.. data:: phpbb3_context
 
     This object supports phpbb3 password hashes, which use a variant of :class:`~passlib.hash.phpass`.
 
 PostgreSQL
 ==========
-.. object:: postgres_context
+.. data:: postgres_context
 
     This object should recognize password hashes stores in PostgreSQL's ``pg_shadow`` table;
     which are all assumed to follow the :class:`~passlib.hash.postgres_md5` format.
diff --git a/docs/lib/passlib.context-options.rst b/docs/lib/passlib.context-options.rst
index 1cf6000..d2202b7 100644
--- a/docs/lib/passlib.context-options.rst
+++ b/docs/lib/passlib.context-options.rst
@@ -1,3 +1,6 @@
+.. index::
+    single: CryptContext; constructor options
+
 .. _cryptcontext-options:
 
 =============================================
@@ -225,4 +228,3 @@ And the equivalent as a set of python keyword options::
         admin__sha512_crypt__min_rounds = 100000
         admin__bcrypt__min_rounds = 13
     )
-
diff --git a/docs/lib/passlib.hosts.rst b/docs/lib/passlib.hosts.rst
index a47f799..7bf8308 100644
--- a/docs/lib/passlib.hosts.rst
+++ b/docs/lib/passlib.hosts.rst
@@ -19,23 +19,23 @@ Interface
 PassLib provides :class:`!CryptContext` instances
 for the following Unix variants:
 
-.. object:: linux_context
+.. data:: linux_context
 
     context instance which recognizes hashes used
     by the majority of Linux distributions.
     encryption defaults to :class:`!sha512_crypt`.
 
-.. object:: freebsd_context
+.. data:: freebsd_context
 
     context instance which recognizes all hashes used by FreeBSD 8.
     encryption defaults to :class:`!bcrypt`.
 
-.. object:: netbsd_context
+.. data:: netbsd_context
 
     context instance which recognizes all hashes used by NetBSD.
     encryption defaults to :class:`!bcrypt`.
 
-.. object:: openbsd_context
+.. data:: openbsd_context
 
     context instance which recognizes all hashes used by OpenBSD.
     encryption defaults to :class:`!bcrypt`.
@@ -90,7 +90,7 @@ A quick usage example, using the :data:`!linux_context` instance::
 
 Current-Host Contexts
 =====================
-.. object:: host_context
+.. data:: host_context
 
     PassLib provides this object, which will dynamically be an alias
     for one of the above context instances (based on ``sys.platform``).
diff --git a/docs/lib/passlib.utils.h64.rst b/docs/lib/passlib.utils.h64.rst
index e467508..5ba5b6e 100644
--- a/docs/lib/passlib.utils.h64.rst
+++ b/docs/lib/passlib.utils.h64.rst
@@ -24,7 +24,7 @@ and decoding strings in that format.
 
 Constants
 =========
-.. object:: CHARS = "./0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+.. data:: CHARS = "./0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
 
     The character set used by the Hash-64 format.
     A character's index in CHARS denotes it's corresponding 6-bit integer value.
diff --git a/docs/overview.rst b/docs/overview.rst
index d72f094..3e62714 100644
--- a/docs/overview.rst
+++ b/docs/overview.rst
@@ -76,7 +76,8 @@ in order to get users started quickly:
 
     For new applications which just need drop-in support for some manner
     of password encryption, so they can secure store passwords
-    and then forget about it, they should see :data:`passlib.apps.custom_app_context`.
+    and then forget about it, they should use
+    the :data:`passlib.apps.custom_app_context` object.
 
 A quick example of how a password context can be used::
 
diff --git a/docs/password_hash_api.rst b/docs/password_hash_api.rst
index 878a081..99a9ed3 100644
--- a/docs/password_hash_api.rst
+++ b/docs/password_hash_api.rst
@@ -1,3 +1,5 @@
+.. index:: password hash api
+
 .. _password-hash-api:
 
 =================
@@ -179,8 +181,9 @@ which scheme a hash belongs to when multiple schemes are in use.
         Common settings keywords include ``salt`` and ``rounds``.
 
     :raises ValueError:
-        * if settings are invalid and not correctable.
-          (eg: provided salt contains invalid characters / length).
+        * if settings are invalid and handler cannot correct them.
+          (eg: a provided salt contains invalid characters / length
+          causes an error, but an out of range rounds value is silently clipped).
 
         * if a context kwd contains an invalid value, or was required
           but omitted.
@@ -189,6 +192,8 @@ which scheme a hash belongs to when multiple schemes are in use.
           this should rarely occur, since most modern algorithms have no limitations
           on the types of characters.
 
+    :raises TypeError: if :samp:`{secret}` is not a string
+
     :returns:
         Hash string, encoded in algorithm-specific format.
 
@@ -202,7 +207,7 @@ which scheme a hash belongs to when multiple schemes are in use.
     :returns:
         * ``True`` if input appears to be a hash string belonging to this algorithm.
         * ``True`` if input appears to be a configuration string belonging to this algorithm.
-        * ``False`` if no input is specified
+        * ``False`` if no input is an empty string or ``None``.
         * ``False`` if none of the above conditions was met.
 
     .. note::
@@ -229,6 +234,7 @@ which scheme a hash belongs to when multiple schemes are in use.
         in :attr:`~PasswordHash.context_kwds`.
 
     :raises TypeError:
+
         * if the secret is not a string.
 
     :raises ValueError: