Get docs building cleanly.

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

Author: craigcitro

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__ = '[email protected] (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):