From 962cf74715ccd4cc9448eff2276bf490519a85cf Mon Sep 17 00:00:00 2001 From: Craig Citro Date: Mon, 5 Jan 2015 11:36:15 -0800 Subject: [PATCH] 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 | 3 +- doc-build | 19 +++++++---- docs/conf.py | 7 +++- docs/django_settings.py | 1 + docs/fetch_gae_sdk.py | 74 +++++++++++++++++++++++++++++++++++++++++ oauth2client/client.py | 2 +- tox.ini | 14 +++++++- 7 files changed, 109 insertions(+), 11 deletions(-) create mode 100644 docs/django_settings.py create mode 100755 docs/fetch_gae_sdk.py diff --git a/.gitignore b/.gitignore index fa898a4..0f9cab3 100644 --- a/.gitignore +++ b/.gitignore @@ -4,8 +4,9 @@ oauth2client.egg-info/ build/ dist/ -# Built documentation +# Documentation-related docs/_build +/google_appengine/ # Test files .tox/ diff --git a/doc-build b/doc-build index 749c83a..327999f 100755 --- a/doc-build +++ b/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) -# -# 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. +# Build the oauth2client docs, installing the GAE SDK as needed. +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 diff --git a/docs/conf.py b/docs/conf.py index 4776ed0..c7d8f73 100644 --- a/docs/conf.py +++ b/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 ---------------------------------------------- diff --git a/docs/django_settings.py b/docs/django_settings.py new file mode 100644 index 0000000..dd524da --- /dev/null +++ b/docs/django_settings.py @@ -0,0 +1 @@ +SECRET_KEY = 'abcdefg' diff --git a/docs/fetch_gae_sdk.py b/docs/fetch_gae_sdk.py new file mode 100755 index 0000000..f0d696b --- /dev/null +++ b/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 [] + +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: {} []'.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[:])) diff --git a/oauth2client/client.py b/oauth2client/client.py index 4007560..73c6ddf 100644 --- a/oauth2client/client.py +++ b/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 diff --git a/tox.ini b/tox.ini index 45da06b..c1952f5 100644 --- a/tox.ini +++ b/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}