docs: pypi redirect msg replaced w/ cloud_sptheme's auto_redirect helper,

building now uses $SPHINX_BUILD_TAGS env var.

4 files changed, 28 insertions, 21 deletions

diff --git a/admin/upload.sh b/admin/upload.sh
index 8b6c321..be3b047 100755
--- a/admin/upload.sh
+++ b/admin/upload.sh
@@ -47,7 +47,7 @@ if [ -z "$SKIP_PYPI" ]; then
 
     # upload docs
     echo "\n$SEP1\nbuilding and uploading docs to pypi\n$SEP2"
-    PASSLIB_DOCS="for-pypi" python setup.py build_sphinx $UPLOAD_DOCS_ARG
+    SPHINX_BUILD_TAGS="for-pypi" python setup.py build_sphinx $UPLOAD_DOCS_ARG
 
 fi
 
diff --git a/docs/conf.py b/docs/conf.py
index 6883743..ab34062 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -6,6 +6,11 @@ This file is execfile()d with the current directory set to its containing dir.
 Note that not all possible configuration values are present in this
 autogenerated file. All configuration values have a default; values that are
 commented out serve to show the default.
+
+This honors the following sphinx tags (passed via -t or $SPHINX_BUILD_TAGS):
+
+    * for-pypi -- generate special version to upload to pypi
+
 """
 #=============================================================================
 # environment setup
@@ -31,9 +36,10 @@ warnings.filterwarnings("ignore", category=DeprecationWarning,
 
 import datetime
 
-# build option flags:
-# "for-pypi" -- enable analytics tracker for pypi documentation
-options = os.environ.get("PASSLIB_DOCS", "").split(",")
+# read env var for tags, needed since "python setup.py build_sphinx"
+# doesn't support sphinx-build's "-t" option.
+for _tag in os.environ.get("SPHINX_BUILD_TAGS", "").split():
+    tags.add(_tag)
 
 # building the docs requires the Cloud Sphinx theme & extensions (>= v1.4),
 # which contains some sphinx extensions used by Passlib.
@@ -45,7 +51,7 @@ import cloud_sptheme as csp
 #=============================================================================
 
 # If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = '1.3'
+needs_sphinx = '1.4'
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
@@ -109,8 +115,6 @@ from passlib import __version__ as release
 version = csp.get_version(release)
 if ".dev" in release:
     tags.add("devcopy")
-if 'for-pypi' in options:
-    tags.add("pypi")
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -199,11 +203,6 @@ if csp.is_cloud_theme(html_theme):
                               toc_local_bg_color='#FFE8C4',
                               toc_local_trim_color='#FFC68A',
                               )
-    if 'for-pypi' in options:
-        html_theme_options.update(
-            googleanalytics_id = 'UA-22302196-2',
-            googleanalytics_path = '/passlib/',
-        )
 
 # Add any paths that contain custom themes here, relative to this directory.
 html_theme_path = [csp.get_theme_dir()]
@@ -274,6 +273,22 @@ html_sidebars = {'**': ['searchbox.html', 'globaltoc.html']}
 htmlhelp_basename = project + 'Doc'
 
 #=============================================================================
+# site-specific html output
+#=============================================================================
+if tags.has("for-pypi"):
+
+    extensions.append('cloud_sptheme.ext.auto_redirect')
+    auto_redirect_domain_url = "https://passlib.readthedocs.io"
+    auto_redirect_domain_root = "/en/stable"
+
+    if csp.is_cloud_theme(html_theme):
+
+        html_theme_options.update(
+            googleanalytics_id = 'UA-22302196-2',
+            googleanalytics_path = '/passlib/',
+        )
+
+#=============================================================================
 # Options for LaTeX output
 #=============================================================================
 
diff --git a/docs/index.rst b/docs/index.rst
index 8409ef9..95d54b4 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -19,14 +19,6 @@ Passlib |release| documentation
         For documentation of the latest stable version,
         see `<https://passlib.readthedocs.io>`_.
 
-.. only:: pypi
-
-   .. warning::
-
-        The official Passlib documentation have moved to `<https://passlib.readthedocs.io>`_.
-        Documentation at this location is still being maintained,
-        but will be updated much less frequently.
-
 Welcome
 =======
 Passlib is a password hashing library for Python 2 & 3, which provides
diff --git a/docs/install.rst b/docs/install.rst
index be11d5d..1809c18 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -139,7 +139,7 @@ If you wish to generate your own copy of the documentation,
 you will need to:
 
 1. Install `Sphinx <http://sphinx.pocoo.org/>`_ (1.4 or newer)
-2. Install the `Cloud Sphinx Theme <http://packages.python.org/cloud_sptheme>`_ (1.8.2 or newer).
+2. Install the `Cloud Sphinx Theme <http://packages.python.org/cloud_sptheme>`_ (1.9.2 or newer).
 3. Download the Passlib source
 4. From the Passlib source directory, run :samp:`python setup.py build_sphinx`.
 5. Once Sphinx completes its run, point a web browser to the file at :samp:`{SOURCE}/build/sphinx/html/index.html`