docs: large reorganization of documentation

* reordering into 'narrative' and 'reference' sections,
  to take advantage of 'fulltoc' extension making
  all pages visible in sidebar.

* styling updates, requires latest cloud_sptheme

* wording improvements to various bits of content

8 files changed, 200 insertions, 99 deletions

diff --git a/docs/lib/passlib.context-tutorial.rst b/docs/lib/passlib.context-tutorial.rst
index 19bdb2b..9d0cdc3 100644
--- a/docs/lib/passlib.context-tutorial.rst
+++ b/docs/lib/passlib.context-tutorial.rst
@@ -3,12 +3,11 @@
 .. _context-overview:
 .. _context-tutorial:
 
-=========================================================
-:mod:`passlib.context` - CryptContext Overview & Tutorial
-=========================================================
+.. currentmodule:: passlib.context
 
-.. module:: passlib.context
-    :synopsis: CryptContext class, for managing multiple password hash schemes
+==============================================
+:mod:`passlib.context` - CryptContext Tutorial
+==============================================
 
 Overview
 ========
@@ -26,7 +25,7 @@ password hashes at once:
 The following sections contain a walkthrough of this class, starting
 with some simple examples, and working up to a complex "full-integration" example.
 
-.. seealso:: The :ref:`CryptContext Reference <context-reference>` document,
+.. seealso:: The :mod:`passlib.context` api reference,
     which lists all the options and methods supported by this class.
 
 .. index:: CryptContext; usage examples
diff --git a/docs/lib/passlib.context.rst b/docs/lib/passlib.context.rst
index 72524e8..ecb954d 100644
--- a/docs/lib/passlib.context.rst
+++ b/docs/lib/passlib.context.rst
@@ -1,11 +1,12 @@
 .. index:: CryptContext; reference
 
-.. currentmodule:: passlib.context
+.. module:: passlib.context
+    :synopsis: CryptContext class, for managing multiple password hash schemes
 
 .. _context-reference:
 
 ======================================================
-:mod:`passlib.context` - CryptContext Reference
+:mod:`passlib.context` - CryptContext
 ======================================================
 This page provides a complete reference of all the methods
 and options supported by the :class:`!CryptContext` class
@@ -16,7 +17,7 @@ and helper utilities.
     * :ref:`CryptContext Overview & Tutorial <context-overview>` --
       overview of this class and walkthrough of how to use it.
 
-.. rst-class:: emphasize-children
+.. rst-class:: emphasize-children toc-always-open
 
 The CryptContext Class
 ======================
@@ -45,7 +46,7 @@ The CryptContext Class
 
 .. index:: CryptContext; keyword options
 
-.. rst-class:: html-toggle expanded
+.. rst-class:: html-toggle expanded toc-always-open
 
 Constructor Keywords
 --------------------
diff --git a/docs/lib/passlib.exc.rst b/docs/lib/passlib.exc.rst
index f90f330..4b36a2b 100644
--- a/docs/lib/passlib.exc.rst
+++ b/docs/lib/passlib.exc.rst
@@ -1,6 +1,6 @@
-===============================================================
-:mod:`passlib.exc` - exceptions and warnings raised by Passlib
-===============================================================
+============================================
+:mod:`passlib.exc` - Exceptions and warnings
+============================================
 
 .. module:: passlib.exc
     :synopsis: exceptions & warnings raised by Passlib
diff --git a/docs/lib/passlib.hash.bcrypt.rst b/docs/lib/passlib.hash.bcrypt.rst
index e5a7a56..946c5ff 100644
--- a/docs/lib/passlib.hash.bcrypt.rst
+++ b/docs/lib/passlib.hash.bcrypt.rst
@@ -82,11 +82,14 @@ you need to upgrade the external package being used as the backend
 
 Format & Algorithm
 ==================
-Bcrypt is compatible with the :ref:`modular-crypt-format`, and uses ``$2$`` and ``$2a$`` as the identifying prefix
-for all its strings (``$2$`` is seen only for legacy hashes which used an older version of Bcrypt).
+Bcrypt is compatible with the :ref:`modular-crypt-format`, and uses a number of identifying
+prefixes: ``$2$``, ``$2a$``, ``$2x$``, ``$2y$``, and ``$2b$``.  Each prefix indicates
+a different revision of the BCrypt algorithm; and all but the ``$2b$`` identifier are
+considered deprecated.
+
 An example hash (of ``password``) is:
 
-  ``$2a$12$GhvMmNVjRW29ulnudl.LbuAnUtN/LRfe1JsBm1Xu6LE3059z5Tr8m``
+  ``$2b$12$GhvMmNVjRW29ulnudl.LbuAnUtN/LRfe1JsBm1Xu6LE3059z5Tr8m``
 
 Bcrypt hashes have the format :samp:`$2a${rounds}${salt}{checksum}`, where:
 
diff --git a/docs/lib/passlib.hash.rst b/docs/lib/passlib.hash.rst
index e17b710..03a28b1 100644
--- a/docs/lib/passlib.hash.rst
+++ b/docs/lib/passlib.hash.rst
@@ -8,20 +8,30 @@
 Overview
 ========
 The :mod:`!passlib.hash` module contains all the password hash algorithms built into Passlib.
-While each hash has its own options and output format, they all share a common interface,
-documented in detail in the :ref:`password-hash-api`. The following pages
-describe the common interface, and then describe each hash in detail
-(including its format, underlying algorithm, and known security issues).
+While each hash has its own options and output format,
+they all inherit from the :mod:`passlib.ifc`.\ :class:`!PasswordHash` API.
+The following pages describe each hash in detail,
+including its format, underlying algorithm, and known security issues.
 
-.. seealso:: :doc:`Quickstart Guide </new_app_quickstart>` -- advice on
-    choosing an appropriately secure hash for your new application.
+.. warning::
+
+    **Many of the hash algorithms listed below are *NOT* secure.**
+
+    Passlib supports a wide array of hash algorithms, primarily to
+    support dealing with legacy data and systems.
+
+    If you're looking to choose a hash algorithm for a new application,
+    see the :doc:`Quickstart Guide </new_app_quickstart>` instead of picking
+    one from this list.
+
+.. rst-class:: html-toggle
 
 Usage
-=====
-All of the hashes in this module can used in two ways:
+-----
+All of the hashes in this module can be used in two ways:
 
-1. They can be imported and used directly, as in the following example
-   with the :class:`md5_crypt` hash::
+1. They can be imported from :mod:`!passlib.hash` and used directly,
+   as in the following example with the :class:`md5_crypt` hash::
 
         >>> # import the desired hash
         >>> from passlib.hash import md5_crypt
@@ -61,87 +71,124 @@ All of the hashes in this module can used in two ways:
         >>> pwd_context.verify("letmein", hash2)
         True
 
-For additional details, usage examples, and full documentation of all
-methods and attributes provided by the common hash interface:
-
-.. toctree::
-    :maxdepth: 2
+.. seealso::
 
-    /password_hash_api
+    For additional details and usage examples, see the
+    :doc:`PasswordHash </password_hash_api>` and :doc:`CryptContext </lib/passlib.context>`
+    reference.
 
 .. _mcf-hashes:
 
-Unix & "Modular Crypt" Hashes
-=============================
-Aside from the "archaic" schemes below, most modern Unix flavors
-use password hashes which follow the :ref:`modular crypt format <modular-crypt-format>`,
+Unix Hashes
+===========
+Aside from "archaic" schemes such as :class:`!des_crypt`,
+most of the password hashes supported by modern Unix flavors
+adhere to the :ref:`modular crypt format <modular-crypt-format>`,
 allowing them to be easily distinguished when used within the same file.
-The basic format :samp:`${scheme}${hash}` has also been adopted for use
+The basic of format :samp:`${scheme}${hash}` has also been adopted for use
 by other applications and password hash schemes.
 
-.. _archaic-unix-schemes:
+.. _standard-unix-hashes:
 
-Archaic Unix Schemes
---------------------
-All of the following hashes are/were used by various Unix flavors
-to store user passwords; most are based on the DES block cipher,
-and predate the arrival of the modular crypt format.
-They should all be considered insecure at best, but may be useful when reading
-legacy password entries:
+.. rst-class:: toc-always-open
+
+Active Unix Hashes
+------------------
+All these schemes are actively in use by various Unix flavors to store user passwords.
+They all follow the modular crypt format.
 
 .. toctree::
     :maxdepth: 1
 
-    passlib.hash.des_crypt
-    passlib.hash.bsdi_crypt
-    passlib.hash.bigcrypt
-    passlib.hash.crypt16
+    passlib.hash.bcrypt
+    passlib.hash.sha256_crypt
+    passlib.hash.sha512_crypt
 
-.. _standard-unix-hashes:
+Special note should be made of the following fallback helper,
+which is not an actual hash scheme, but implements the "disabled account marker"
+found in many Linux & BSD password files:
 
-Standard Unix Schemes
----------------------
-All these schemes are currently used by various Unix flavors to store user passwords.
-They all follow the modular crypt format.
+.. toctree::
+    :maxdepth: 1
+
+    passlib.hash.unix_disabled
+
+.. rst-class:: toc-always-open
+
+Deprecated Unix Hashes
+----------------------
+The following schemes are supported by various Unix systems
+use the modular crypt format, and are noticably stronger than the previous group.
+However, they have all since been deprecated in favor of stronger algorithms:
+
+* :class:`passlib.hash.bsd_nthash` - FreeBSD's MCF-compatible encoding of :doc:`nthash <passlib.hash.nthash>` digests
 
 .. toctree::
     :maxdepth: 1
 
     passlib.hash.md5_crypt
-    passlib.hash.bcrypt
     passlib.hash.sha1_crypt
     passlib.hash.sun_md5_crypt
-    passlib.hash.sha256_crypt
-    passlib.hash.sha512_crypt
 
-Other Modular Crypt Schemes
----------------------------
-While most of these schemes are not (commonly) used by any Unix flavor to store user passwords,
-they can be used compatibly along side other modular crypt format hashes.
+.. _archaic-unix-schemes:
+
+.. rst-class:: toc-always-open
+
+Archaic Unix Hashes
+-------------------
+The following schemes are supported by certain Unix systems,
+but are considered particularly archaic: Not only do they predate
+the modular crypt format, but they're based on the outmoded DES block cipher,
+and are woefully insecure:
 
 .. toctree::
     :maxdepth: 1
 
-    passlib.hash.apr_md5_crypt
+    passlib.hash.des_crypt
+    passlib.hash.bsdi_crypt
+    passlib.hash.bigcrypt
+    passlib.hash.crypt16
+
+Other "Modular Crypt" Hashes
+============================
+The :ref:`modular crypt format <modular-crypt-format>` is a loose standard
+for password hash strings which started life under the Unix operating system,
+and is used by many of the Unix hashes (above).  However, it's
+it's basic :samp:`${scheme}${hash}` format has also been adopted by a number
+of application-specific hash algorithms:
+
+.. rst-class:: toc-always-open
+
+Active Hashes
+-------------
+While most of these schemes generally require an application-specific
+implementation, natively used by any Unix flavor to store user passwords,
+they can be used compatibly along side other modular crypt format hashes:
+
+.. toctree::
+    :maxdepth: 1
+
+    passlib.hash.argon2
     passlib.hash.bcrypt_sha256
     passlib.hash.phpass
     passlib.hash.pbkdf2_digest
-    passlib.hash.cta_pbkdf2_sha1
-    passlib.hash.dlitz_pbkdf2_sha1
     passlib.hash.scram
     passlib.hash.scrypt
-    passlib.hash.argon2
 
-* :class:`passlib.hash.bsd_nthash` - FreeBSD's MCF-compatible :doc:`nthash <passlib.hash.nthash>` encoding
+.. rst-class:: toc-always-open
 
-Special note should be made of the fallback helper,
-which is not an actual hash scheme, but provides "disabled account"
-behavior found in many Linux & BSD password files:
+Deprecated Hashes
+-----------------
+The following are some additional application-specific hashes which are still
+occasionally seen, use the modular crypt format, but are rarely used or weak
+enough that they have been deprecated:
 
 .. toctree::
     :maxdepth: 1
 
-    passlib.hash.unix_disabled
+    passlib.hash.apr_md5_crypt
+    passlib.hash.cta_pbkdf2_sha1
+    passlib.hash.dlitz_pbkdf2_sha1
 
 .. _ldap-hashes:
 
@@ -152,9 +199,6 @@ All of the following hashes use a variant of the password hash format
 used by LDAPv2. Originally specified in :rfc:`2307` and used by OpenLDAP [#openldap]_,
 the basic format ``{SCHEME}HASH`` has seen widespread adoption in a number of programs.
 
-.. [#openldap] OpenLDAP homepage - `<http://www.openldap.org/>`_.
-
-
 .. _standard-ldap-hashes:
 
 Standard LDAP Schemes
@@ -237,13 +281,11 @@ no identifying markers, identifying them is pretty much context-dependant.
     passlib.hash.msdcc
     passlib.hash.msdcc2
 
-.. _other-hashes:
+.. rst-class:: toc-always-toggle
 
-Other Hashes
+Cisco Hashes
 ============
-The following schemes are used in various contexts,
-but have formats or uses which cannot be easily placed
-in one of the above categories:
+The following hashes are used in various places on Cisco IOS and ASA devices:
 
 .. toctree::
     :maxdepth: 1
@@ -251,13 +293,31 @@ in one of the above categories:
     passlib.hash.cisco_pix
     passlib.hash.cisco_asa
 
-* *Cisco "Type 5" hashes* - see :doc:`md5_crypt <passlib.hash.md5_crypt>`
+* **Cisco "Type 5" hashes** - these are the same as :doc:`md5_crypt <passlib.hash.md5_crypt>`
 
 .. toctree::
     :maxdepth: 1
 
     passlib.hash.cisco_type7
+
+.. _other-hashes:
+
+Other Hashes
+============
+The following schemes are used in various contexts,
+but have formats or uses which cannot be easily placed
+in one of the above categories:
+
+.. toctree::
+    :maxdepth: 1
+
     passlib.hash.django_std
     passlib.hash.grub_pbkdf2_sha512
     passlib.hash.hex_digests
     passlib.hash.plaintext
+
+.. rubric:: Footnotes
+
+.. [#openldap] OpenLDAP homepage - `<http://www.openldap.org/>`_.
+
+
diff --git a/docs/lib/passlib.pwd.rst b/docs/lib/passlib.pwd.rst
index 0b4b556..505230c 100644
--- a/docs/lib/passlib.pwd.rst
+++ b/docs/lib/passlib.pwd.rst
@@ -2,7 +2,7 @@
     :synopsis: password generation helpers
 
 =================================================
-:mod:`passlib.pwd` -- password generation helpers
+:mod:`passlib.pwd` -- Password generation helpers
 =================================================
 
 .. versionadded:: 1.7
diff --git a/docs/lib/passlib.totp-tutorial.rst b/docs/lib/passlib.totp-tutorial.rst
new file mode 100644
index 0000000..0982825
--- /dev/null
+++ b/docs/lib/passlib.totp-tutorial.rst
@@ -0,0 +1,36 @@
+.. index:: TOTP; overview
+.. _totp-tutorial:
+
+.. currentmodule:: passlib.totp
+
+===================================
+:mod:`passlib.totp` - TOTP Tutorial
+===================================
+
+Overview
+========
+The :mod:`passlib.totp` module provides a set of classes for adding
+two-factor authentication (2FA) support into your application,
+using the widely supported TOTP / HOTP specifications.
+
+This module provides a number of classes, designed to support a variety
+of use cases, including:
+
+    * Low-level methods for calculating tokens on the client side.
+
+    * Low-level methods for generating OTP keys & verifying tokens on the server side.
+
+    * High level methods for server-side storage of OTP keys *along with
+      state and history*, making it easy to add TOTP integration.
+
+.. seealso:: The :mod:`passlib.totp` api reference,
+    which lists all details of all the classes and methods mentioned here.
+
+.. index:: TOTP; usage examples
+
+.. rst-class:: emphasize-children
+
+Tutorial / Walkthrough
+======================
+
+.. todo:: this content needs writing
\ No newline at end of file
diff --git a/docs/lib/passlib.totp.rst b/docs/lib/passlib.totp.rst
index fdb5fe4..961bf46 100644
--- a/docs/lib/passlib.totp.rst
+++ b/docs/lib/passlib.totp.rst
@@ -5,14 +5,14 @@
 :mod:`passlib.totp` -- TOTP / Two Factor Authentication
 =======================================================
 
-.. versionadded:: 1.7
-
 .. todo::
 
     This module is still a work in progress, it's API may change before release.
 
     Things left:
 
+    * convert TOTP 'offset' to 'skew' (inverting sense)
+    * TOTO & helper should track *next* counter, to match HTOP (as well as default reuse=False behavior)
     * finish unittests (there are a few cases left)
     * write narrative documentation
     * get api documentation formatted better (whether by getting nested sections integrated into TOC,
@@ -24,34 +24,35 @@
     * more verification against other TOTP servers & clients.
     * consider native pyqrcode integration (e.g. a ``to_qrcode()`` method)
 
-.. rst-class:: emphasize-children
+.. versionadded:: 1.7
+
+The :mod:`!passlib.totp` module provides a number of classes for implementing
+two-factor authentication (2FA) using the TOTP / HOTP specifications.
+This page provides a reference to all the classes and methods in this module.
 
-API Reference
-=============
+.. seealso::
+
+    * :ref:`TOTP Tutorial <totp-overview>` --
+      overview of this module and walkthrough of how to use it.
+
+.. rst-class:: emphasize-children
 
 OTPContext
-----------
+==========
 .. autoclass:: OTPContext
 
 .. autofunction:: generate_secret
 
 Common Interface
-----------------
+================
 .. autoclass:: BaseOTP()
 
 TOTP (Timed-based tokens)
--------------------------
+=========================
 .. autoclass:: TOTP(key=None, format="base32", \*, new=False, \*\*kwds)
 
-Helper Classes
-..............
-
-.. autoclass:: TotpToken()
-
-.. autoclass:: TotpMatch()
-
 HOTP (Counter-based tokens)
----------------------------
+===========================
 .. note::
 
     HOTP is used much less frequently, since it's fragile
@@ -60,9 +61,10 @@ HOTP (Counter-based tokens)
 
 .. autoclass:: HOTP(key=None, format="base32", \*, new=False, \*\*kwds)
 
-Helper Classes
-..............
-
+Support Classes
+===============
+.. autoclass:: TotpToken()
+.. autoclass:: TotpMatch()
 .. autoclass:: HotpMatch()
 
 Deviations