Get docs building cleanly.

Still need to wire up `tox -e doc`.

doc-build

@@ -22,8 +22,5 @@
 # Notes: You may have to update the location of the
 # App Engine library for your local system.
 
-[[ -d docs ]] || mkdir -p docs
 cd docs
-export DJANGO_SETTINGS_MODULE=fakesettings
-export PYTHONPATH=$(pwd)/..
-epydoc --output epy --graph all --parse-only --docformat plaintext oauth2client
+make html

docs/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS =
+SPHINXOPTS = -W
 SPHINXBUILD = sphinx-build
 PAPER =
 BUILDDIR = _build

docs/conf.py

@@ -55,10 +55,12 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
+
+import oauth2client
 # The short X.Y version.
-version = '1.4.4'
+version = oauth2client.__version__
 # The full version, including alpha/beta/rc tags.
-release = '1.4.4'
+release = oauth2client.__version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -107,7 +109,7 @@
 
 import sphinx_bootstrap_theme
 
-html_logo = 'google_logo.png'
+html_logo = '_static/google_logo.png'
 html_theme = 'bootstrap'
 html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
 html_theme_options = {

docs/contributing.rst

@@ -8,11 +8,11 @@ Please fill out either the individual or corporate Contributor License
 Agreement.
 
 * If you are an individual writing original source code and you're sure you
-own the intellectual property, then you'll need to sign an `individual CLA
-<https://developers.google.com/open-source/cla/individual>`_.
+ own the intellectual property, then you'll need to sign an `individual CLA
+ <https://developers.google.com/open-source/cla/individual>`_.
 * If you work for a company that wants to allow you to contribute your work to
-oauth2client, then you'll need to sign a `corporate CLA
-<https://developers.google.com/open-source/cla/corporate>`_.
+ oauth2client, then you'll need to sign a `corporate CLA
+ <https://developers.google.com/open-source/cla/corporate>`_.
 
 Follow either of the
 two links above to access the appropriate CLA and instructions for how to sign

docs/index.rst

@@ -44,3 +44,9 @@ Please see the `contributing page <contributing.html>`_ for more information.
 In particular, we love pull requests -- but please make sure to sign the
 contributor license agreement.
 
+.. toctree::
+ :maxdepth: 1
+ :hidden:
+
+ source/modules
+ contributing

oauth2client/appengine.py

@@ -571,16 +571,14 @@ class OAuth2Decorator(object):
  Instantiate and then use with oauth_required or oauth_aware
  as decorators on webapp.RequestHandler methods.
 
- Example:
+ ::
 
  decorator = OAuth2Decorator(
  client_id='837...ent.com',
  client_secret='Qh...wwI',
  scope='https://www.googleapis.com/auth/plus')
 
-
  class MainHandler(webapp.RequestHandler):
-
  @decorator.oauth_required
  def get(self):
  http = decorator.http()
@@ -847,7 +845,8 @@ def callback_path(self):
  def callback_handler(self):
  """RequestHandler for the OAuth 2.0 redirect callback.
 
- Usage:
+ Usage::
+
  app = webapp.WSGIApplication([
  ('/index', MyIndexHandler),
  ...,
@@ -910,20 +909,19 @@ class OAuth2DecoratorFromClientSecrets(OAuth2Decorator):
  Uses a clientsecrets file as the source for all the information when
  constructing an OAuth2Decorator.
 
- Example:
+ ::
 
  decorator = OAuth2DecoratorFromClientSecrets(
  os.path.join(os.path.dirname(__file__), 'client_secrets.json')
  scope='https://www.googleapis.com/auth/plus')
 
-
  class MainHandler(webapp.RequestHandler):
-
  @decorator.oauth_required
  def get(self):
  http = decorator.http()
  # http is authorized with the user's Credentials and can be used
  # in API calls
+
  """
 
  @util.positional(3)

oauth2client/client.py

@@ -499,13 +499,13 @@ def authorize(self, http):
  it.
 
  Args:
- http: An instance of httplib2.Http
- or something that acts like it.
+ http: An instance of ``httplib2.Http`` or something that acts
+ like it.
 
  Returns:
  A modified instance of http that was passed in.
 
- Example:
+ Example::
 
  h = httplib2.Http()
  h = credentials.authorize(h)
@@ -515,6 +515,7 @@ def authorize(self, http):
  signing. So instead we have to overload 'request' with a closure
  that adds in the Authorization header and then calls the original
  version of 'request()'.
+
  """
  request_orig = http.request
 
@@ -859,7 +860,8 @@ class AccessTokenCredentials(OAuth2Credentials):
 
  AccessTokenCredentials objects may be safely pickled and unpickled.
 
- Usage:
+ Usage::
+
  credentials = AccessTokenCredentials('<an access token>',
  'my-user-agent/1.0')
  http = httplib2.Http()
@@ -1688,8 +1690,8 @@ class DeviceFlowInfo(collections.namedtuple('DeviceFlowInfo', (
  def FromResponse(cls, response):
  """Create a DeviceFlowInfo from a server response.
 
- The response should be a dict containing entries as described
- here:
+ The response should be a dict containing entries as described here:
+
  http://tools.ietf.org/html/draft-ietf-oauth-v2-05#section-3.7.1
  """
  # device_code, user_code, and verification_url are required.

oauth2client/clientsecrets.py

@@ -112,10 +112,12 @@ def loadfile(filename, cache=None):
  Typical cache storage would be App Engine memcache service,
  but you can pass in any other cache client that implements
  these methods:
- - get(key, namespace=ns)
- - set(key, value, namespace=ns)
 
- Usage:
+ * ``get(key, namespace=ns)``
+ * ``set(key, value, namespace=ns)``
+
+ Usage::
+
  # without caching
  client_type, client_info = loadfile('secrets.json')
  # using App Engine memcache service

oauth2client/locked_file.py

@@ -17,7 +17,8 @@
 This module first tries to use fcntl locking to ensure serialized access
 to a file, then falls back on a lock file if that is unavialable.
 
-Usage:
+Usage::
+
  f = LockedFile('filename', 'r+b', 'rb')
  f.open_and_lock()
  if f.is_locked():
@@ -26,6 +27,7 @@
  else:
  print('Acquired filename with rb mode')
  f.unlock_and_close()
+
 """
 
 from __future__ import print_function

oauth2client/multistore_file.py

@@ -19,26 +19,29 @@
 both in a single process and across processes.
 
 The credential themselves are keyed off of:
+
 * client_id
 * user_agent
 * scope
 
-The format of the stored data is like so:
-{
- 'file_version': 1,
- 'data': [
- {
- 'key': {
- 'clientId': '<client id>',
- 'userAgent': '<user agent>',
- 'scope': '<scope>'
- },
- 'credential': {
- # JSON serialized Credentials.
+The format of the stored data is like so::
+
+ {
+ 'file_version': 1,
+ 'data': [
+ {
+ 'key': {
+ 'clientId': '<client id>',
+ 'userAgent': '<user agent>',
+ 'scope': '<scope>'
+ },
+ 'credential': {
+ # JSON serialized Credentials.
+ }
  }
- }
- ]
-}
+ ]
+ }
+
 """
 
 __author__ = 'jbeda@google.com (Joe Beda)'
@@ -62,12 +65,10 @@
 
 class Error(Exception):
  """Base error for this module."""
- pass
 
 
 class NewerCredentialStoreError(Error):
- """The credential store is a newer version that supported."""
- pass
+ """The credential store is a newer version than supported."""
 
 
 @util.positional(4)

oauth2client/util.py

@@ -51,56 +51,58 @@
 def positional(max_positional_args):
  """A decorator to declare that only the first N arguments my be positional.
 
- This decorator makes it easy to support Python 3 style key-word only
- parameters. For example, in Python 3 it is possible to write:
+ This decorator makes it easy to support Python 3 style keyword-only
+ parameters. For example, in Python 3 it is possible to write::
 
  def fn(pos1, *, kwonly1=None, kwonly1=None):
  ...
 
- All named parameters after * must be a keyword:
+ All named parameters after ``*`` must be a keyword::
 
  fn(10, 'kw1', 'kw2') # Raises exception.
  fn(10, kwonly1='kw1') # Ok.
 
- Example:
-  To define a function like above, do:
+ Example
+ ^^^^^^^
 
- @positional(1)
- def fn(pos1, kwonly1=None, kwonly2=None):
- ...
+ To define a function like above, do::
+
+ @positional(1)
+ def fn(pos1, kwonly1=None, kwonly2=None):
+ ...
 
-  If no default value is provided to a keyword argument, it becomes a required
-  keyword argument:
+ If no default value is provided to a keyword argument, it becomes a required
+ keyword argument::
 
-  @positional(0)
-  def fn(required_kw):
-  ...
+ @positional(0)
+ def fn(required_kw):
+ ...
 
-  This must be called with the keyword parameter:
+ This must be called with the keyword parameter::
 
-  fn() # Raises exception.
-  fn(10) # Raises exception.
-  fn(required_kw=10) # Ok.
+ fn() # Raises exception.
+ fn(10) # Raises exception.
+ fn(required_kw=10) # Ok.
 
-  When defining instance or class methods always remember to account for
-  'self' and 'cls':
+ When defining instance or class methods always remember to account for
+ ``self`` and ``cls``::
 
-  class MyClass(object):
+ class MyClass(object):
 
-  @positional(2)
-  def my_method(self, pos1, kwonly1=None):
-  ...
+ @positional(2)
+ def my_method(self, pos1, kwonly1=None):
+ ...
 
-  @classmethod
-  @positional(2)
-  def my_method(cls, pos1, kwonly1=None):
-  ...
+ @classmethod
+ @positional(2)
+ def my_method(cls, pos1, kwonly1=None):
+ ...
 
  The positional decorator behavior is controlled by
- util.positional_parameters_enforcement, which may be set to
- POSITIONAL_EXCEPTION, POSITIONAL_WARNING or POSITIONAL_IGNORE to raise an
- exception, log a warning, or do nothing, respectively, if a declaration is
- violated.
+ ``util.positional_parameters_enforcement``, which may be set to
+ ``POSITIONAL_EXCEPTION``, ``POSITIONAL_WARNING`` or
+ ``POSITIONAL_IGNORE`` to raise an exception, log a warning, or do
+ nothing, respectively, if a declaration is violated.
 
  Args:
  max_positional_arguments: Maximum number of positional arguments. All
@@ -114,6 +116,7 @@ def my_method(cls, pos1, kwonly1=None):
  TypeError if a key-word only argument is provided as a positional
  parameter, but only if util.positional_parameters_enforcement is set to
  POSITIONAL_EXCEPTION.
+
  """
  def positional_decorator(wrapped):
  def positional_wrapper(*args, **kwargs):