Merge "Cleanup doc warnings and enforce warning-is-error in sphinx"

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.

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"]):

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}

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
     (<idp_id>, <protocol_id>). Using the values found, a IdP/protocol
     specific URL will be constructed:
+
         /auth/OS-FEDERATION/identity_providers/<idp_id>
         /protocols/<protocol_id>/websso
 
     If no value is found from the WEBSSO_IDP_MAPPING dictionary, it will
     treat the value as the global WebSSO protocol <protocol_id> and
     construct the WebSSO URL by:
+
         /auth/OS-FEDERATION/websso/<protocol_id>
 
     :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()}
 

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