From 289dfa865f78e9625161428f223f5c2202d4bd6f Mon Sep 17 00:00:00 2001 From: Craig Citro Date: Thu, 18 Dec 2014 17:00:07 -0800 Subject: [PATCH] Get docs building cleanly. Still need to wire up `tox -e doc`. --- doc-build | 5 +-- docs/Makefile | 2 +- docs/conf.py | 8 ++-- docs/contributing.rst | 8 ++-- docs/index.rst | 6 +++ oauth2client/appengine.py | 12 +++--- oauth2client/client.py | 14 ++++--- oauth2client/clientsecrets.py | 8 ++-- oauth2client/locked_file.py | 4 +- oauth2client/multistore_file.py | 37 ++++++++++--------- oauth2client/util.py | 65 +++++++++++++++++---------------- 11 files changed, 91 insertions(+), 78 deletions(-) diff --git a/doc-build b/doc-build index f678c3026..749c83afc 100755 --- a/doc-build +++ b/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 diff --git a/docs/Makefile b/docs/Makefile index 46ca8ec51..6ed721dfd 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = +SPHINXOPTS = -W SPHINXBUILD = sphinx-build PAPER = BUILDDIR = _build diff --git a/docs/conf.py b/docs/conf.py index 6c0bfc772..4776ed091 100644 --- a/docs/conf.py +++ b/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 = { diff --git a/docs/contributing.rst b/docs/contributing.rst index 45a67933b..ec61397ae 100644 --- a/docs/contributing.rst +++ b/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 -`_. + own the intellectual property, then you'll need to sign an `individual CLA + `_. * 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 -`_. + oauth2client, then you'll need to sign a `corporate CLA + `_. Follow either of the two links above to access the appropriate CLA and instructions for how to sign diff --git a/docs/index.rst b/docs/index.rst index 7f6a9c709..82002f7c4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -44,3 +44,9 @@ Please see the `contributing page `_ 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 diff --git a/oauth2client/appengine.py b/oauth2client/appengine.py index 7321dcb92..00fe9855d 100644 --- a/oauth2client/appengine.py +++ b/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) diff --git a/oauth2client/client.py b/oauth2client/client.py index ae0301d59..b7cefc549 100644 --- a/oauth2client/client.py +++ b/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('', '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. diff --git a/oauth2client/clientsecrets.py b/oauth2client/clientsecrets.py index 9c94471a6..b4c6f5217 100644 --- a/oauth2client/clientsecrets.py +++ b/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 diff --git a/oauth2client/locked_file.py b/oauth2client/locked_file.py index 5a75dac59..af92398ed 100644 --- a/oauth2client/locked_file.py +++ b/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 diff --git a/oauth2client/multistore_file.py b/oauth2client/multistore_file.py index 135f22471..a2750f33a 100644 --- a/oauth2client/multistore_file.py +++ b/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': '', - 'userAgent': '', - 'scope': '' - }, - 'credential': { - # JSON serialized Credentials. +The format of the stored data is like so:: + + { + 'file_version': 1, + 'data': [ + { + 'key': { + 'clientId': '', + 'userAgent': '', + '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) diff --git a/oauth2client/util.py b/oauth2client/util.py index ab1e450a2..72cd8718c 100644 --- a/oauth2client/util.py +++ b/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):