documentation building should now be done through 'setup.py build_sphinx';

changed instructions accordingly;
also added 'docdist' setup command to build doc zip files

5 files changed, 91 insertions, 10 deletions

diff --git a/docs/install.rst b/docs/install.rst
index 4bb4558..4d13b9d 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -66,14 +66,14 @@ and are designed to be run using the
 Once PassLib and Nose have been installed, the tests may be run from the source directory::
 
     # to run the platform-relevant tests...
-    nosetests -v passlib/tests
+    nosetests -v --tests passlib/tests
 
     # to run all tests...
-    PASSLIB_TESTS="all" nosetests -v passlib/tests
+    PASSLIB_TESTS="all" nosetests -v --tests passlib/tests
 
     # to run nose with the optional coverage plugin...
     # (results will be in build/coverage)
-    PASSLIB_TESTS="all" nosetests -v passlib/tests --with-coverage \
+    PASSLIB_TESTS="all" nosetests -v --tests passlib/tests --with-coverage \
         --cover-package=passlib --cover-html --cover-html-dir build/coverage
 
 (There will be a large proportion of skipped tests, this is normal).
@@ -86,9 +86,11 @@ online at `<http://packages.python.org/passlib>`_.
 If you wish to generate your own copy of the documentation,
 you will need to:
 
-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:`{$SOURCE}/docs/_build/html/index.html`
+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 setup.py build_sphinx`.
+5. Once Sphinx completes it's run, point a web browser to the file at :samp:`{$SOURCE}/build/sphinx/html/index.html`
    to access the PassLib documentation in html format.
+6. Alternately, steps 4 & 5 can be replaced by running :samp:`python setup.py docdist`,
+   which will build a zip file of the documentation in :samp:`{$SOURCE}/dist`.
\ No newline at end of file
diff --git a/passlib/_setup/docdist.py b/passlib/_setup/docdist.py
new file mode 100644
index 0000000..cc8fcfa
--- /dev/null
+++ b/passlib/_setup/docdist.py
@@ -0,0 +1,69 @@
+"custom command to build doc.zip file"
+#=========================================================
+#imports
+#=========================================================
+#core
+import os
+from distutils import dir_util
+from distutils.cmd import Command
+#local
+__all__ = [
+    "docdist"
+]
+#=========================================================
+#command
+#=========================================================
+class docdist(Command):
+
+    description = "create zip file containing standalone html docs"
+    
+    user_options = [
+        ('build-dir=', None, 'Build directory'),
+        ('dist-dir=', 'd',
+         "directory to put the source distribution archive(s) in "
+         "[default: dist]"),        
+        ('format=', 'f',
+         "archive format to create (tar, ztar, gztar, zip)"),
+    ]
+    
+    def initialize_options(self):
+        self.build_dir = None
+        self.dist_dir = None
+        self.format = None
+        self.keep_temp = False
+        
+    def finalize_options(self):
+        if self.build_dir is None:
+            cmd = self.get_finalized_command('build')
+            self.build_dir = os.path.join(cmd.build_base, 'docdist')
+        if not self.dist_dir:
+            self.dist_dir = "dist"
+        if not self.format:
+            self.format = "zip"
+            
+    def run(self):
+        # call build sphinx to build docs
+        self.run_command("build_sphinx")
+        cmd = self.get_finalized_command("build_sphinx")
+        source_dir = cmd.builder_target_dir
+
+        # copy to directory with appropriate name
+        dist = self.distribution
+        arc_name = "%s-docs-%s" % (dist.get_name(), dist.get_version())
+        tmp_dir = os.path.join(self.build_dir, arc_name)
+        if os.path.exists(tmp_dir):
+            dir_util.remove_tree(tmp_dir, dry_run=self.dry_run)
+        self.copy_tree(source_dir, tmp_dir, preserve_symlinks=True)
+
+        # make archive from dir
+        arc_base = os.path.join(self.dist_dir, arc_name)
+        self.arc_filename = self.make_archive(arc_base, self.format,
+                                              self.build_dir)
+
+        #cleanup
+        if not self.keep_temp:
+            dir_util.remove_tree(tmp_dir, dry_run=self.dry_run)
+    
+#=========================================================
+#eof
+#=========================================================
diff --git a/passlib/utils/handlers.py b/passlib/utils/handlers.py
index 0bdf178..410ffca 100644
--- a/passlib/utils/handlers.py
+++ b/passlib/utils/handlers.py
@@ -172,7 +172,8 @@ class StaticHandler(object):
 
     The default :meth:`verify` method uses simple equality to compare hash strings.
     If your hash may have multiple encoding (eg case-insensitive), this
-    method should be overridden on a per-handler basis.
+    method (or the private :meth:`_norm_hash` method)
+    should be overridden on a per-handler basis.
 
     If your hash has options, such as multiple identifiers, salts,
     or variable rounds, this is not the right class to start with.
diff --git a/setup.cfg b/setup.cfg
index cce5f16..1a0031f 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -2,7 +2,7 @@
 sign = true
 
 [upload_docs]
-upload_dir = docs/_build/html
+upload_dir = build/sphinx/html
 
 [test]
 test_suite = nose.collector
diff --git a/setup.py b/setup.py
index 12c420f..0eb02e7 100644
--- a/setup.py
+++ b/setup.py
@@ -46,6 +46,15 @@ if py3k:
         opts['cmdclass']['build_py'] = build_py
 
 #=========================================================
+#register docdist command (not required)
+#=========================================================
+try:
+    from passlib._setup.docdist import docdist
+    opts['cmdclass']['docdist'] = docdist
+except ImportError:
+    pass
+
+#=========================================================
 # version string / datestamps
 #=========================================================
 from passlib import __version__ as VERSION