Override oauthlib docstrings that fail with Sphinx 1.7.5

Sphinx 1.7.5 has some breaking changes that treat a couple specific
warnings as errors. Keystone isn't failing on them directly, but we
do rely on an interface from oauthlib/oauthlib that has compatibility
issues with that version of Sphinx.

This commit overrides those comments in keystone's implementation of
the interface so that we can get our documentation job passing. Once
the oauthlib docstrings are fixed upstream, we can consume a version
of oauthlib that addresses those incompatibilities and remove the
duplication introduced here. This has been reported upstream in the
following GitHub issue:

  https://github.com/oauthlib/oauthlib/issues/558

Change-Id: I197bc346ffb2ed75ba68aa2e9c2f82a0cad163e6
Partial-Bug: 1778603

keystone/oauth1/validator.py

@@ -88,6 +88,35 @@ class OAuthValidator(provider_api.ProviderAPIMixin, oauth1.RequestValidator):
         return ''
 
     def invalidate_request_token(self, client_key, request_token, request):
+        """Invalidate a used request token.
+
+        :param client_key: The client/consumer key.
+        :param request_token: The request token string.
+        :param request: An oauthlib.common.Request object.
+        :returns: None
+
+        Per `Section 2.3`_ of the spec:
+
+        "The server MUST (...) ensure that the temporary
+        credentials have not expired or been used before."
+
+        .. _`Section 2.3`: https://tools.ietf.org/html/rfc5849#section-2.3
+
+        This method should ensure that provided token won't validate anymore.
+        It can be simply removing RequestToken from storage or setting
+        specific flag that makes it invalid (note that such flag should be
+        also validated during request token validation).
+
+        This method is used by
+
+        * AccessTokenEndpoint
+        """
+        # FIXME(lbragstad): Remove the above documentation string once
+        # https://bugs.launchpad.net/keystone/+bug/1778603 is resolved. It is
+        # being duplicated here to work around oauthlib compatibility issues
+        # with Sphinx 1.7.5, which have been reported upstream in
+        # https://github.com/oauthlib/oauthlib/issues/558.
+
         # this method is invoked when an access token is generated out of a
         # request token, to make sure that request token cannot be consumed
         # anymore. This is done in the backend, so we do nothing here.
@@ -177,6 +206,29 @@ class OAuthValidator(provider_api.ProviderAPIMixin, oauth1.RequestValidator):
 #                                            token["oauth_token_secret"])
 
     def save_verifier(self, token, verifier, request):
+        """Associate an authorization verifier with a request token.
+
+        :param token: A request token string.
+        :param verifier: A dictionary containing the oauth_verifier and
+                         oauth_token
+        :param request: An oauthlib.common.Request object.
+
+        We need to associate verifiers with tokens for validation during the
+        access token request.
+
+        Note that unlike save_x_token token here is the ``oauth_token`` token
+        string from the request token saved previously.
+
+        This method is used by
+
+        * AuthorizationEndpoint
+        """
+        # FIXME(lbragstad): Remove the above documentation string once
+        # https://bugs.launchpad.net/keystone/+bug/1778603 is resolved. It is
+        # being duplicated here to work around oauthlib compatibility issues
+        # with Sphinx 1.7.5, which have been reported upstream in
+        # https://github.com/oauthlib/oauthlib/issues/558.
+
         # keep the old logic for this, as it is done in two steps and requires
         # information that the request validator has no access to
         pass