updated documentation to use some cloud_sptheme 1.3 features

* escaped {} literals in *samp* roles - used on some doc pages
* google analytics integration for pypi docs

4 files changed, 28 insertions, 16 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 422c558..c9011cc 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -13,7 +13,7 @@
 
 import sys, os
 
-options = os.environ.get("PASSLIB_DOCS", "")
+options = os.environ.get("PASSLIB_DOCS", "").split(",")
 
 #make sure passlib in sys.path
 doc_root = os.path.abspath(os.path.join(__file__,os.path.pardir))
@@ -28,7 +28,7 @@ sys.path.insert(0, source_root)
 #building the docs requires the Cloud sphinx theme & extensions
 # https://bitbucket.org/ecollins/cloud_sptheme
 #which contains some sphinx extensions used by passlib
-import cloud_sptheme
+import cloud_sptheme as csp
 
 #hack to make autodoc generate documentation from the correct class...
 from passlib.utils import md4
@@ -42,12 +42,21 @@ needs_sphinx = '1.0'
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
+    # standard sphinx extensions
     'sphinx.ext.autodoc',
     'sphinx.ext.todo',
 
-    'cloud_sptheme.ext.autodoc_sections', #add autdoc support for ReST sections in class/function docstrings
-    'cloud_sptheme.ext.index_styling', #adds extra ids & classes to genindex html, for additional styling
-    'cloud_sptheme.ext.relbar_toc', #inserts toc into right hand nav bar (ala old style python docs)
+    #add autdoc support for ReST sections in class/function docstrings
+    'cloud_sptheme.ext.autodoc_sections',
+
+    #adds extra ids & classes to genindex html, for additional styling
+    'cloud_sptheme.ext.index_styling',
+
+    #inserts toc into right hand nav bar (ala old style python docs)
+    'cloud_sptheme.ext.relbar_toc',
+
+    # replace sphinx :samp: role handler with one that allows escaped {} chars
+    'cloud_sptheme.ext.escaped_samp_literals',
     ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -75,7 +84,7 @@ copyright = u'2008-2011, Assurance Technologies, LLC'
 # version: The short X.Y version.
 # release: The full version, including alpha/beta/rc tags.
 from passlib import __version__ as release
-version = cloud_sptheme.get_version(release)
+version = csp.get_version(release)
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -128,12 +137,15 @@ html_theme = 'cloud'
 # further.  For a list of options available for each theme, see the
 # documentation.
 if html_theme == 'cloud':
-    html_theme_options = { "roottarget": index_doc }
+    html_theme_options = { "roottarget": index_doc, "collapsiblesidebar": True }
+    if 'for-pypi' in options:
+        html_theme_options['googleanalytics_id'] = 'UA-22302196-2'
+        html_theme_options['googleanalytics_path'] = '/passlib/'
 else:
     html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = [cloud_sptheme.get_theme_dir()]
+html_theme_path = [csp.get_theme_dir()]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
diff --git a/docs/lib/passlib.context-options.rst b/docs/lib/passlib.context-options.rst
index 3792da1..629a2b1 100644
--- a/docs/lib/passlib.context-options.rst
+++ b/docs/lib/passlib.context-options.rst
@@ -174,7 +174,7 @@ number of rounds for that scheme, or just a longer verify time.
 If an application wishes to use this feature, it all that is needed
 is to prefix the name of any hash or context options with the name
 of the category string it wants to use, and add an additional separator to the keyword:
-:samp:`{category}__{hash}__{option}`` or ``{category}__context__{option}``.
+:samp:`{category}__{hash}__{option}`` or :samp:`{category}__context__{option}`.
 
 .. note::
 
diff --git a/docs/lib/passlib.hash.atlassian_pbkdf2_sha1.rst b/docs/lib/passlib.hash.atlassian_pbkdf2_sha1.rst
index 1aaa953..4bd4892 100644
--- a/docs/lib/passlib.hash.atlassian_pbkdf2_sha1.rst
+++ b/docs/lib/passlib.hash.atlassian_pbkdf2_sha1.rst
@@ -33,8 +33,8 @@ Interface
 Format & Algorithm
 ==================
 
-All of this scheme's hashes have the format :``{PKCS5S2}<data>``,
-where :samp:`<data>` is a 64 character base64 encoded string;
+All of this scheme's hashes have the format :samp:`\\{PKCS5S2\\}{data}`,
+where :samp:`{data}` is a 64 character base64 encoded string;
 which (when decoded), contains a 16 byte salt,
 and a 32 byte checksum.
 
diff --git a/docs/lib/passlib.hash.fshp.rst b/docs/lib/passlib.hash.fshp.rst
index 407d7ac..54de676 100644
--- a/docs/lib/passlib.hash.fshp.rst
+++ b/docs/lib/passlib.hash.fshp.rst
@@ -56,24 +56,24 @@ Interface
 Format & Algorithm
 ==================
 
-All of this scheme's hashes have the format: ``{FSHP<variant>|<saltsize>|<rounds>}<data>``.
+All of this scheme's hashes have the format: :samp:`\\{FSHP{variant}|{saltsize}|{rounds}\\}{data}`.
 A example hash (of ``password``) is:
 
     ``{FSHP1|16|16384}PtoqcGUetmVEy/uR8715TNqKa8+teMF9qZO1lA9lJNUm1EQBLPZ+qPRLeEPHqy6C``
 
-* :samp:`<variant>` is a decimal integer identifying the version of FSHP;
+* :samp:`{variant}` is a decimal integer identifying the version of FSHP;
   in particular, which cryptographic hash function should be used
   to calculate the checksum. ``1`` in the example.
   (see the class description above for a list of possible values).
 
-* :samp:`<saltsize>` is a decimal integer identifying the number of bytes
+* :samp:`{saltsize}` is a decimal integer identifying the number of bytes
   in the salt. ``16`` in the example.
 
-* :samp:`<rounds>` is a decimal integer identifying the number
+* :samp:`{rounds}` is a decimal integer identifying the number
   of rounds to apply when calculating the checksum (see below).
   ``16384`` in the example.
 
-* :samp:`<data>` is a base64-encoded string which, when decoded,
+* :samp:`{data}` is a base64-encoded string which, when decoded,
   contains a salt string of the specified size, followed
   by the checksum. In the example, the data portion decodes to
   a salt value (in hexdecimal octets) of: