From bc5f1df5a997b2c8e36871327f2853abe13ee0af Mon Sep 17 00:00:00 2001 From: Akihiro Motoki Date: Fri, 24 Mar 2017 22:58:47 +0900 Subject: [PATCH] Cleanup doc warnings and enforce warning-is-error in sphinx * doc/source/conf.py: html_static_path pointed to nonexisting dir * Fix indent error in python codes * Insert blank lines before starting code block * Enable warning-is-error in setup.cfg to prevent future warnings * 'all_files' should be 'all-files' in setup.cfg Change-Id: I7c5bc31be9c95ec78f18f895014a03cb003d7e04 --- doc/source/conf.py | 2 +- openstack_auth/backend.py | 7 +++++-- openstack_auth/user.py | 11 ++++++----- openstack_auth/utils.py | 22 +++++++++++++++------- setup.cfg | 3 ++- 5 files changed, 29 insertions(+), 16 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 3e4c09cf..661d794b 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -113,7 +113,7 @@ html_theme = 'default' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +#html_static_path = [] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. diff --git a/openstack_auth/backend.py b/openstack_auth/backend.py index c8acd216..bc1d345e 100644 --- a/openstack_auth/backend.py +++ b/openstack_auth/backend.py @@ -68,8 +68,11 @@ class KeystoneBackend(object): If authenticated, this return the user object based on the user ID and session data. - Note: this required monkey-patching the ``contrib.auth`` middleware - to make the ``request`` object available to the auth backend class. + .. note:: + + This required monkey-patching the ``contrib.auth`` middleware + to make the ``request`` object available to the auth backend class. + """ if (hasattr(self, 'request') and user_id == self.request.session["user_id"]): diff --git a/openstack_auth/user.py b/openstack_auth/user.py index 06debc64..3edb2044 100644 --- a/openstack_auth/user.py +++ b/openstack_auth/user.py @@ -259,8 +259,9 @@ class User(models.AbstractBaseUser, models.AnonymousUser): def is_token_expired(self, margin=None): """Determine if the token is expired. - Returns ``True`` if the token is expired, ``False`` if not, and - ``None`` if there is no token set. + :returns: + ``True`` if the token is expired, ``False`` if not, and + ``None`` if there is no token set. :param margin: A security time margin in seconds before real expiration. @@ -287,7 +288,7 @@ class User(models.AbstractBaseUser, models.AnonymousUser): def is_anonymous(self): """Return if the user is not authenticated. - Returns ``True`` if not authenticated,``False`` otherwise. + :returns: ``True`` if not authenticated,``False`` otherwise. """ return deprecation.CallableBool(not self.is_authenticated) else: @@ -307,7 +308,7 @@ class User(models.AbstractBaseUser, models.AnonymousUser): def is_anonymous(self, margin=None): """Return if the user is not authenticated. - Returns ``True`` if not authenticated,``False`` otherwise. + :returns: ``True`` if not authenticated,``False`` otherwise. :param margin: A security time margin in seconds before end of an eventual @@ -327,7 +328,7 @@ class User(models.AbstractBaseUser, models.AnonymousUser): def is_superuser(self): """Evaluates whether this user has admin privileges. - Returns ``True`` or ``False``. + :returns: ``True`` or ``False``. """ admin_roles = utils.get_admin_roles() user_roles = {role['name'].lower() for role in self.roles} diff --git a/openstack_auth/utils.py b/openstack_auth/utils.py index 0d5ee110..3d49b7a8 100644 --- a/openstack_auth/utils.py +++ b/openstack_auth/utils.py @@ -186,6 +186,7 @@ def get_websso_url(request, auth_url, websso_auth): :type websso_auth: string Example of horizon WebSSO setting:: + WEBSSO_CHOICES = ( ("credentials", "Keystone Credentials"), ("oidc", "OpenID Connect"), @@ -207,12 +208,14 @@ def get_websso_url(request, auth_url, websso_auth): The value in WEBSSO_IDP_MAPPING is expected to be a tuple formatted as (, ). Using the values found, a IdP/protocol specific URL will be constructed: + /auth/OS-FEDERATION/identity_providers/ /protocols//websso If no value is found from the WEBSSO_IDP_MAPPING dictionary, it will treat the value as the global WebSSO protocol and construct the WebSSO URL by: + /auth/OS-FEDERATION/websso/ :returns: Keystone WebSSO endpoint. @@ -436,12 +439,14 @@ def using_cookie_backed_sessions(): def get_admin_roles(): """Common function for getting the admin roles from settings - Returns: - Set object including all admin roles. - If there is no role, this will return empty. + :return: + Set object including all admin roles. + If there is no role, this will return empty:: + { "foo", "bar", "admin" } + """ admin_roles = {role.lower() for role in getattr(settings, 'OPENSTACK_KEYSTONE_ADMIN_ROLES', @@ -454,9 +459,10 @@ def get_role_permission(role): This format is 'openstack.roles.xxx' and 'xxx' is a real role name. - Returns: + :returns: String like "openstack.roles.admin" If role is None, this will return None. + """ return "openstack.roles.%s" % role.lower() @@ -466,14 +472,16 @@ def get_admin_permissions(): This format is 'openstack.roles.xxx' and 'xxx' is a real role name. - Returns: - Set object including all admin permission. - If there is no permission, this will return empty. + :returns: + Set object including all admin permission. + If there is no permission, this will return empty:: + { "openstack.roles.foo", "openstack.roles.bar", "openstack.roles.admin" } + """ return {get_role_permission(role) for role in get_admin_roles()} diff --git a/setup.cfg b/setup.cfg index e7fd682b..c34ebb22 100644 --- a/setup.cfg +++ b/setup.cfg @@ -29,7 +29,8 @@ packages = openstack_auth [build_sphinx] -all_files = 1 +all-files = 1 +warning-is-error = 1 build-dir = doc/build source-dir = doc/source