Automate doc creation.

This adds several pieces for doc creation:

 * a script to automate fetching the GAE SDK,
 * updates `doc-build` to fetch the SDK and use sphinx,
 * a dummy `django_settings` module where needed,
 * a `tox` target to build, and
 * use of `ghp-import` to push the changes into the gh-pages branch.

.gitignore

@@ -4,8 +4,9 @@ oauth2client.egg-info/
 build/
 dist/
 
-# Built documentation
+# Documentation-related
 docs/_build
+/google_appengine/
 
 # Test files
 .tox/

doc-build

@@ -14,13 +14,18 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-# Author: jcgregorio@google.com (Joe Gregorio)
+# Build the oauth2client docs, installing the GAE SDK as needed.
-#
-# Creates the documentation set for the library by
-# running pydoc on all the files in apiclient.
-#
-# Notes: You may have to update the location of the
-#        App Engine library for your local system.
 
+set -e
+
+if [[ -z "${SKIP_GAE_SDK}" ]]; then
+  docs/fetch_gae_sdk.py
+  export PYTHONPATH="${PWD}/google_appengine:${PYTHONPATH}"
+fi
+
+rm -rf docs/_build/* docs/source/*
+sphinx-apidoc -f -o docs/source oauth2client
 cd docs
 make html
+cd ..
+ghp-import -n docs/_build/html

docs/conf.py

@@ -31,8 +31,8 @@ import os
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.coverage',
+    'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
-    'sphinxcontrib.napoleon',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -100,6 +100,11 @@ pygments_style = 'sphinx'
 # If true, keep warnings as "system message" paragraphs in the built documents.
 #keep_warnings = False
 
+# In order to load django before 1.7, we need
+import django
+if django.VERSION[1] < 7:
+  sys.path.insert(0, '.')
+  os.environ['DJANGO_SETTINGS_MODULE'] = 'django_settings'
 
 # -- Options for HTML output ----------------------------------------------
 

docs/django_settings.py

@@ -0,0 +1 @@
+SECRET_KEY = 'abcdefg'

docs/fetch_gae_sdk.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python
+"""Fetch the most recent GAE SDK and decompress it in the current directory.
+
+Usage:
+  fetch_gae_sdk.py [<dest_dir>]
+
+Current releases are listed here:
+  https://www.googleapis.com/storage/v1/b/appengine-sdks/o?prefix=featured
+"""
+
+import json
+import os
+import StringIO
+import sys
+import tempfile
+import urllib2
+import zipfile
+
+_SDK_URL = (
+    'https://www.googleapis.com/storage/v1/b/appengine-sdks/o?prefix=featured')
+
+def get_gae_versions():
+  try:
+    version_info_json = urllib2.urlopen(_SDK_URL).read()
+  except:
+    return {}
+  try:
+    version_info = json.loads(version_info_json)
+  except:
+    return {}
+  return version_info.get('items', {})
+
+def _version_tuple(v):
+  version_string = os.path.splitext(v['name'])[0].rpartition('_')[2]
+  return tuple(int(x) for x in version_string.split('.'))
+
+def get_sdk_url(sdk_versions):
+  python_releases = [v for v in sdk_versions
+                     if v['name'].startswith('featured/google_appengine')]
+  current_release = sorted(python_releases, key=_version_tuple)[-1]
+  return current_release['mediaLink']
+
+def main(argv):
+  if len(argv) > 2:
+    print 'Usage: {} [<destination_dir>]'.format(argv[0])
+    return 1
+  dest_dir = argv[1] if len(argv) > 1 else '.'
+  if not os.path.exists(dest_dir):
+    os.makedirs(dest_dir)
+
+  if os.path.exists(os.path.join(dest_dir, 'google_appengine')):
+    print 'GAE SDK already installed at {}, exiting.'.format(dest_dir)
+    return 0
+
+  sdk_versions = get_gae_versions()
+  if not sdk_versions:
+    print 'Error fetching GAE SDK version info'
+    return 1
+  sdk_url = get_sdk_url(sdk_versions)
+  try:
+    sdk_contents = StringIO.StringIO(urllib2.urlopen(sdk_url).read())
+  except:
+    print 'Could not read SDK from', sdk_url
+    return 1
+  sdk_contents.seek(0)
+  try:
+    zip_contents = zipfile.ZipFile(sdk_contents)
+    zip_contents.extractall(dest_dir)
+  except:
+    print 'Error extracting SDK contents'
+    return 1
+
+if __name__ == '__main__':
+  sys.exit(main(sys.argv[:]))

oauth2client/client.py

@@ -93,7 +93,7 @@ AccessTokenInfo = collections.namedtuple(
 
 DEFAULT_ENV_NAME = 'UNKNOWN'
 class SETTINGS(object):
-  """Settings namespace for globally."""
+  """Settings namespace for globally defined values."""
   env_name = None
 
 

tox.ini

@@ -5,7 +5,7 @@ envlist = py26,py27,py33,py34,pypy,cover
 basedeps = keyring
            mock
            pycrypto==2.6
-           django>=1.5,<1.6
+           django
            webtest
            nose
 deps = {[testenv]basedeps}
@@ -36,6 +36,18 @@ deps =
     {[testenv:cover]deps}
     coveralls
 
+[testenv:docs]
+basepython = python2.7
+deps =
+    {[testenv:cover]deps}
+    ghp-import
+    python-gflags
+    pyyaml
+    sphinx
+    sphinx-bootstrap-theme
+    sphinx-rtd-theme
+commands = ./doc-build
+
 [testenv:py26openssl13]
 basepython = python2.6
 deps = {[testenv]basedeps}