From a15dd80dd29e56a6ba195c5414532fcbb1d40a29 Mon Sep 17 00:00:00 2001 From: Jamie Lennox Date: Mon, 15 Dec 2014 12:16:39 +1000 Subject: [PATCH] Fix up types within API documentation Correct the type signature of some API documentation. Add inter-sphinx mapping to documentation to provide links to external docs. Correct some phrases and errors. Change-Id: Id4a71a9901e5adc695afed656e3bc84e4e54e67a --- doc/source/conf.py | 6 +++++ keystoneclient/auth/base.py | 24 ++++++++++++-------- keystoneclient/auth/cli.py | 2 ++ keystoneclient/auth/conf.py | 8 ++++--- keystoneclient/auth/identity/base.py | 14 +++++++++++- keystoneclient/auth/identity/generic/base.py | 3 ++- keystoneclient/auth/identity/v3.py | 3 ++- keystoneclient/client.py | 7 +++--- 8 files changed, 49 insertions(+), 18 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 30d025944..f256fd463 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -42,6 +42,7 @@ sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage', + 'sphinx.ext.intersphinx', 'oslosphinx', # NOTE(blk-u): Uncomment the [pbr] section in setup.cfg and # remove this Sphinx extension when @@ -232,3 +233,8 @@ latex_documents = [ # If false, no module index is generated. #latex_use_modindex = True + +intersphinx_mapping = { + 'python': ('http://docs.python.org/', None), + 'osloconfig': ('http://docs.openstack.org/developer/oslo.config/', None), +} diff --git a/keystoneclient/auth/base.py b/keystoneclient/auth/base.py index 1f4ce2977..011586c48 100644 --- a/keystoneclient/auth/base.py +++ b/keystoneclient/auth/base.py @@ -34,6 +34,7 @@ def get_plugin_class(name): :param str name: The name of the object to get. :returns: An auth plugin class. + :rtype: :py:class:`keystoneclient.auth.BaseAuthPlugin` :raises keystoneclient.exceptions.NoMatchingPlugin: if a plugin cannot be created. @@ -67,6 +68,8 @@ class BaseAuthPlugin(object): Returning None will indicate that no token was able to be retrieved. :param session: A session object so the plugin can make HTTP calls. + :type session: keystoneclient.session.Session + :return: A token to use. :rtype: string """ @@ -84,8 +87,8 @@ class BaseAuthPlugin(object): - ``interface``: what visibility the endpoint should have. - ``region_name``: the region the endpoint exists in. - :param Session session: The session object that the auth_plugin - belongs to. + :param session: The session object that the auth_plugin belongs to. + :type session: keystoneclient.session.Session :returns: The base URL that will be used to talk to the required service or None if not available. @@ -137,8 +140,8 @@ class BaseAuthPlugin(object): Given a plugin class convert it's options into argparse arguments and add them to a parser. - :param AuthPlugin plugin: an auth plugin class. - :param argparse.ArgumentParser: the parser to attach argparse options. + :param parser: the parser to attach argparse options. + :type parser: argparse.ArgumentParser """ # NOTE(jamielennox): ideally oslo.config would be smart enough to @@ -173,10 +176,11 @@ class BaseAuthPlugin(object): Convert the results of a parse into the specified plugin. - :param AuthPlugin plugin: an auth plugin class. - :param Namespace namespace: The result from CLI parsing. + :param namespace: The result from CLI parsing. + :type namespace: argparse.Namespace :returns: An auth plugin, or None if a name is not provided. + :rtype: :py:class:`keystoneclient.auth.BaseAuthPlugin` """ for opt in cls.get_options(): val = getattr(namespace, 'os_%s' % opt.dest) @@ -190,7 +194,8 @@ class BaseAuthPlugin(object): def register_conf_options(cls, conf, group): """Register the oslo.config options that are needed for a plugin. - :param conf: An oslo.config conf object. + :param conf: A config object. + :type conf: oslo.config.cfg.ConfigOpts :param string group: The group name that options should be read from. """ plugin_opts = cls.get_options() @@ -202,11 +207,12 @@ class BaseAuthPlugin(object): Convert the options already registered into a real plugin. - :param conf: An oslo.config conf object. + :param conf: A config object. + :type conf: oslo.config.cfg.ConfigOpts :param string group: The group name that options should be read from. :returns: An authentication Plugin. - :rtype: plugin: + :rtype: :py:class:`keystoneclient.auth.BaseAuthPlugin` """ plugin_opts = cls.get_options() diff --git a/keystoneclient/auth/cli.py b/keystoneclient/auth/cli.py index ce4f11fdd..40a81c1d4 100644 --- a/keystoneclient/auth/cli.py +++ b/keystoneclient/auth/cli.py @@ -30,6 +30,7 @@ def register_argparse_arguments(parser, argv, default=None): if one isn't specified by the CLI. default: None. :returns: The plugin class that will be loaded or None if not provided. + :rtype: :py:class:`keystoneclient.auth.BaseAuthPlugin` :raises keystoneclient.exceptions.NoMatchingPlugin: if a plugin cannot be created. @@ -68,6 +69,7 @@ def load_from_argparse_arguments(namespace, **kwargs): :param Namespace namespace: The result from CLI parsing. :returns: An auth plugin, or None if a name is not provided. + :rtype: :py:class:`keystoneclient.auth.BaseAuthPlugin` :raises keystoneclient.exceptions.NoMatchingPlugin: if a plugin cannot be created. diff --git a/keystoneclient/auth/conf.py b/keystoneclient/auth/conf.py index 0b68184f1..fdd2aa452 100644 --- a/keystoneclient/auth/conf.py +++ b/keystoneclient/auth/conf.py @@ -60,7 +60,8 @@ def register_conf_options(conf, group): taken. If section is not provided then the auth plugin options will be taken from the same group as provided in the parameters. - :param oslo.config.Cfg conf: config object to register with. + :param conf: config object to register with. + :type conf: oslo.config.cfg.ConfigOpts :param string group: The ini group to register options in. """ conf.register_opt(_AUTH_SECTION_OPT, group=group) @@ -85,11 +86,12 @@ def load_from_conf_options(conf, group, **kwargs): The base options should have been registered with register_conf_options before this function is called. - :param conf: An oslo.config conf object. + :param conf: A conf object. + :type conf: oslo.config.cfg.ConfigOpts :param string group: The group name that options should be read from. :returns: An authentication Plugin or None if a name is not provided - :rtype: plugin + :rtype: :py:class:`keystoneclient.auth.BaseAuthPlugin` :raises keystoneclient.exceptions.NoMatchingPlugin: if a plugin cannot be created. diff --git a/keystoneclient/auth/identity/base.py b/keystoneclient/auth/identity/base.py index 94b071219..b31b7be0b 100644 --- a/keystoneclient/auth/identity/base.py +++ b/keystoneclient/auth/identity/base.py @@ -74,6 +74,9 @@ class BaseIdentityPlugin(base.BaseAuthPlugin): when invoked. If you are looking to just retrieve the current auth data then you should use get_access. + :param session: A session object that can be used for communication. + :type session: keystoneclient.session.Session + :raises keystoneclient.exceptions.InvalidResponse: The response returned wasn't appropriate. @@ -89,6 +92,9 @@ class BaseIdentityPlugin(base.BaseAuthPlugin): If a valid token is not present then a new one will be fetched. + :param session: A session object that can be used for communication. + :type session: keystoneclient.session.Session + :raises keystoneclient.exceptions.HttpError: An error from an invalid HTTP response. @@ -125,6 +131,9 @@ class BaseIdentityPlugin(base.BaseAuthPlugin): If a valid AccessInfo is present then it is returned otherwise a new one will be fetched. + :param session: A session object that can be used for communication. + :type session: keystoneclient.session.Session + :raises keystoneclient.exceptions.HttpError: An error from an invalid HTTP response. @@ -164,6 +173,8 @@ class BaseIdentityPlugin(base.BaseAuthPlugin): If a valid token is not present then a new one will be fetched using the session and kwargs. + :param session: A session object that can be used for communication. + :type session: keystoneclient.session.Session :param string service_type: The type of service to lookup the endpoint for. This plugin will return None (failure) if service_type is not provided. @@ -247,7 +258,8 @@ class BaseIdentityPlugin(base.BaseAuthPlugin): This function is expected to be used by subclasses and should not be needed by users. - :param Session session: A session object to discover with. + :param session: A session object to discover with. + :type session: keystoneclient.session.Session :param str url: The url to lookup. :param bool authenticated: Include a token in the discovery call. (optional) Defaults to None (use a token diff --git a/keystoneclient/auth/identity/generic/base.py b/keystoneclient/auth/identity/generic/base.py index 4fa3c9c89..7c5a80f79 100644 --- a/keystoneclient/auth/identity/generic/base.py +++ b/keystoneclient/auth/identity/generic/base.py @@ -81,7 +81,8 @@ class BaseGenericPlugin(base.BaseIdentityPlugin): params then it should return it. If not return None and then another call will be made with other available URLs. - :param Session session: A session object. + :param session: A session object. + :type session: keystoneclient.session.Session :param tuple version: A tuple of the API version at the URL. :param string url: The base URL for this version. :param string raw_status: The status that was in the discovery field. diff --git a/keystoneclient/auth/identity/v3.py b/keystoneclient/auth/identity/v3.py index 8f723ff0f..cc3a62ce0 100644 --- a/keystoneclient/auth/identity/v3.py +++ b/keystoneclient/auth/identity/v3.py @@ -176,7 +176,8 @@ class AuthMethod(object): def get_auth_data(self, session, auth, headers, **kwargs): """Return the authentication section of an auth plugin. - :param Session session: The communication session. + :param session: The communication session. + :type session: keystoneclient.session.Session :param Auth auth: The auth plugin calling the method. :param dict headers: The headers that will be sent with the auth request if a plugin needs to add to them. diff --git a/keystoneclient/client.py b/keystoneclient/client.py index 8b6a6b012..8de2963c3 100644 --- a/keystoneclient/client.py +++ b/keystoneclient/client.py @@ -28,9 +28,10 @@ def Client(version=None, unstable=False, session=None, **kwargs): at least the specified minor version. For example to specify the 3.1 API use (3, 1). :param bool unstable: Accept endpoints not marked as 'stable'. (optional) - :param Session session: A session object to be used for communication. If - one is not provided it will be constructed from the - provided kwargs. (optional) + :param session: A session object to be used for communication. If one is + not provided it will be constructed from the provided + kwargs. (optional) + :type session: keystoneclient.session.Session :param kwargs: Additional arguments are passed through to the client that is being created. :returns: New keystone client object