Making tweaks to allow project to build on readthedocs.org.

In particular

- Adding a requirements.txt file to aid in installing docs-only
  dependencies (this is a feature of readthedocs, see
  https://docs.readthedocs.org/en/latest/builds.html)
- Updating comment before `import django` in docs/conf.py. Without
  the setup that or tox `docs` env provides or the dependencies
  in docs/requirements.txt, sphinx-build will fail due to missing
  `django`
- Adding a section to docs/conf.py which downloads the
  App Engine SDK and adds it to the import path
- Adding base (non-docs) dir so sources get added when generating
  HTML (e.g. sys.path.append('..') within docs/ dir)
- Using package distribution for docs version instead of manually
  importing oauth2client in docs/conf.py.

docs/conf.py

@@ -4,8 +4,14 @@
 # sphinx-quickstart on Wed Dec 17 23:13:19 2014.
 #
 
-import sys
 import os
+from pkg_resources import get_distribution
+import sys
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath('..'))
 
 # -- General configuration ------------------------------------------------
 
@@ -24,14 +30,16 @@ project = u'oauth2client'
 copyright = u'2014, Google, Inc'
 
 # Version info
-import oauth2client
+distro = get_distribution('oauth2client')
-version = oauth2client.__version__
+version = distro.version
-release = oauth2client.__version__
+release = distro.version
 
 exclude_patterns = ['_build']
 
 # In order to load django before 1.7, we need to create a faux
-# settings module and load it.
+# settings module and load it. This assumes django has been installed
+# (but it must be for the docs to build), so if it has not already
+# been installed run `pip install -r docs/requirements.txt`.
 import django
 if django.VERSION[1] < 7:
   sys.path.insert(0, '.')
@@ -40,7 +48,24 @@ if django.VERSION[1] < 7:
 # -- Options for HTML output ----------------------------------------------
 
 # We want to set the RTD theme, but not if we're on RTD.
-if os.environ.get('READTHEDOCS', '') != 'True':
+if os.environ.get('READTHEDOCS', None) == 'True':
+  # Download the GAE SDK if we are building on READTHEDOCS.
+  docs_dir = os.path.dirname(os.path.abspath(__file__))
+  root_dir = os.path.abspath(os.path.join(docs_dir, '..'))
+  gae_dir = os.path.join(root_dir, 'google_appengine')
+  if not os.path.isdir(gae_dir):
+    scripts_dir = os.path.join(root_dir, 'scripts')
+    sys.path.append(scripts_dir)
+    import fetch_gae_sdk
+    # The first argument is the script name and the second is
+    # the destination dir (where google_appengine is downloaded).
+    result = fetch_gae_sdk.main([None, root_dir])
+    if result not in (0, None):
+      sys.stderr.write('Result failed %d\n' % (result,))
+      sys.exit(result)
+    # Allow imports from the GAE directory as well.
+    sys.path.append(gae_dir)
+else:
   import sphinx_rtd_theme
   html_theme = 'sphinx_rtd_theme'
   html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

docs/requirements.txt

@@ -0,0 +1,9 @@
+django
+flask
+keyring
+pycrypto>=2.6
+pyopenssl>=0.14
+python-gflags
+pyyaml
+webapp2
+WebOb