Docs: fix Sphinx warnings for better ReadTheDocs generation (#807)

JonathanHuot · web-flow · commit 2f887b5a070b · 2022-02-24T07:07:49.000+06:00
* Fix list of current features for 3.2.0 * Renamed travis-ci.org icon URLs * Force fixing the warnings in the docs generation * Removed unused folder reference * Added orphean documents into summary. * Fix docstring formatting example in contributing page. * Removed unused argument from documentation * Fix sphinx warning resulting in loss of formatting in RTD. * Force setuptools until pypa/setuptools#3118 is fixed * Prevent linux redirection in travis instructions * Add graphviz/dot command to generate docs frmo Travis
diff --git a/.travis.yml b/.travis.yml
@@ -22,7 +22,8 @@ jobs:
   allow_failures:
   - python: "3.11-dev"
 before_install:
-  - python -m pip install --upgrade pip setuptools
+  - sudo apt-get install graphviz
+  - python -m pip install --upgrade pip "setuptools<60.9"
   - python -m pip install tox coveralls
   - if [ "$TOXENV" == "pypy3" ]; then curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y && source $HOME/.cargo/env ; fi
 script: tox
diff --git a/README.rst b/README.rst
@@ -4,8 +4,8 @@ OAuthLib - Python Framework for OAuth1 & OAuth2
 *A generic, spec-compliant, thorough implementation of the OAuth request-signing
 logic for Python 3.6+.*
 
-.. image:: https://travis-ci.org/oauthlib/oauthlib.svg?branch=master
-  :target: https://travis-ci.org/oauthlib/oauthlib
+.. image:: https://app.travis-ci.com/oauthlib/oauthlib.svg?branch=master
+  :target: https://app.travis-ci.com/oauthlib/oauthlib
   :alt: Travis
 .. image:: https://coveralls.io/repos/oauthlib/oauthlib/badge.svg?branch=master
   :target: https://coveralls.io/r/oauthlib/oauthlib
diff --git a/docs/Makefile b/docs/Makefile
@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -v
+SPHINXOPTS    = -v -W
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
diff --git a/docs/conf.py b/docs/conf.py
@@ -127,7 +127,7 @@
 # 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 = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
diff --git a/docs/contributing.rst b/docs/contributing.rst
@@ -272,8 +272,12 @@ the autogenerated documentation read more cleanly:
 
 Consolidated example
 
+.. code-block:: python
+
 	def foo(self, request, client, bar=None, key=None):
 		"""
+                This method defines framework for `MAC Access Authentication`_ RFC.
+
 		This method checks the `key` against the `client`. The `request` is
 		passed to maintain context.
 
@@ -283,15 +287,18 @@ Consolidated example
 						   nonce="1336363200:dj83hs9s",
 						   mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM="
 
-		.. _`MAC Access Authentication`: https://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-01
-		
 		:param request: OAuthlib request.
 		:type request: oauthlib.common.Request
-        :param client: Client object set by you, see ``.authenticate_client``.
-		:param bar:
-	    :param key: MAC given provided by token endpoint.
+		:param client: User's defined Client object, see ``.authenticate_client``.
+		:param bar: Another example.
+		:param key: Another param.
+		:return: Explaination of return value and type
+
+		.. _`MAC Access Authentication`: https://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-01
 		"""
 
+
+
 How pull requests are checked, tested, and done
 ===============================================
 
diff --git a/docs/feature_matrix.rst b/docs/feature_matrix.rst
@@ -30,7 +30,7 @@ the request.
 OAuth 2.0
 .........
 
-OAuth 2.0 client and provider support for:
+OAuth 2.0 full client and provider supports for:
 
 - `RFC 6749 section-4.1`_: Authorization Code Grant
 - `RFC 6749 section-4.2`_: Implicit Grant
@@ -40,23 +40,28 @@ OAuth 2.0 client and provider support for:
 - `RFC 6750`_: Bearer Tokens
 - `RFC 7009`_: Token Revocation
 - `RFC 7636`_: Proof Key for Code Exchange by OAuth Public Clients (PKCE)
-- `RFC 8628`_: OAuth2.0 Device Authorization Grant
 - `RFC Draft`_ Message Authentication Code (MAC) Tokens
 
-Partial implementations (any help/PR are welcomed to complete the list):
+Only OAuth2.0 Provider has been implemented:
+
+- `OpenID Connect Core`_
+- `RFC 7662`_: Token Introspection
+- `RFC 8414`_: Authorization Server Metadata
+
+Only OAuth2.0 Client has been implemented:
+
+- `RFC 8628`_: Device Authorization Grant
+
+Missing features:
 
-- OAuth2.0 Provider: `OpenID Connect Core`_
-- OAuth2.0 Provider: `RFC 7662`_: Token Introspection
-- OAuth2.0 Provider: `RFC 8414`_: Authorization Server Metadata
-- OAuth2.0 **Client**: `OpenID Connect Core`_
-- OAuth2.0 **Client**: `RFC 7662`_: Token Introspection
-- OAuth2.0 **Client**: `RFC 8414`_: Authorization Server Metadata
 - SAML2
 - Bearer JWT as Client Authentication
 - Dynamic client registration
 - OpenID Discovery
 - OpenID Session Management
-- ...and more
+
+Any help are welcomed and will be carefully reviewed and integrated to the project. Don't hesitate to be part of the community !
+
 
 Platforms
 .........
diff --git a/docs/oauth2/clients/client.rst b/docs/oauth2/clients/client.rst
@@ -14,6 +14,7 @@ to use them please browse the documentation for each client type below.
     mobileapplicationclient
     legacyapplicationclient
     backendapplicationclient
+    deviceclient
 
 **Existing libraries**
     If you are using the `requests`_ HTTP library you may be interested in using
diff --git a/docs/oauth2/oidc/grants.rst b/docs/oauth2/oidc/grants.rst
@@ -39,3 +39,4 @@ checks the presence of `openid` scope in the parameters.
    authcode
    implicit
    hybrid
+   refresh_token
diff --git a/docs/oauth2/oidc/id_tokens.rst b/docs/oauth2/oidc/id_tokens.rst
@@ -11,7 +11,8 @@ See examples below.
 
 .. _`ID Tokens`: http://openid.net/specs/openid-connect-core-1_0.html#IDToken
 
-.. autoclass:: oauthlib.oauth2.RequestValidator
+.. autoclass:: oauthlib.openid.RequestValidator
+   :noindex:
    :members: finalize_id_token
 
 
diff --git a/docs/oauth2/oidc/refresh_token.rst b/docs/oauth2/oidc/refresh_token.rst
@@ -1,4 +1,4 @@
-OpenID Authorization Code
+OpenID Refresh Grant
 -------------------------
 
 .. autoclass:: oauthlib.openid.connect.core.grant_types.RefreshTokenGrant
diff --git a/docs/oauth2/oidc/validator.rst b/docs/oauth2/oidc/validator.rst
@@ -1,17 +1,17 @@
 Creating a Provider
-=============================================
+===================
 
 .. contents::
    :depth: 2
 
 1. Create an OIDC provider
------------------------
+--------------------------
 If you don't have an OAuth2.0 Provider, you can follow the instructions at
 :doc:`OAuth2.0 Creating a Provider </oauth2/server>`. Then, follow the
 migration step below.
 
 2. Migrate your OAuth2.0 provider into an OIDC provider
-----------------------------------------------------
+-------------------------------------------------------
 
 If you have a OAuth2.0 provider running and want to upgrade to OIDC, you can
 upgrade it by replacing one line of code:
diff --git a/docs/release_process.rst b/docs/release_process.rst
@@ -26,7 +26,7 @@ changes and pings the primary contacts for each downstream project.  Please
 respond within those 2 days if you have major concerns. 
 
 How to get on the notifications list
------------------------------------
+------------------------------------
 
 Which projects and the instructions for testing each will be defined in
 OAuthLibs ``Makefile``.  To add your project, simply open a pull request or
diff --git a/oauthlib/oauth1/rfc5849/request_validator.py b/oauthlib/oauth1/rfc5849/request_validator.py
@@ -443,7 +443,7 @@ def invalidate_request_token(self, client_key, request_token, request):
         :type request: oauthlib.common.Request
         :returns: None
 
-        Per `Section 2.3`__ of the spec:
+        Per `Section 2.3`_ of the spec:
 
         "The server MUST (...) ensure that the temporary
         credentials have not expired or been used before."
@@ -831,7 +831,7 @@ 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
+        :param verifier: A dictionary containing the oauth_verifier and
                         oauth_token
         :param request: OAuthlib request.
         :type request: oauthlib.common.Request
diff --git a/oauthlib/oauth2/rfc6749/clients/base.py b/oauthlib/oauth2/rfc6749/clients/base.py
diff --git a/oauthlib/oauth2/rfc6749/endpoints/introspect.py b/oauthlib/oauth2/rfc6749/endpoints/introspect.py
diff --git a/oauthlib/oauth2/rfc6749/request_validator.py b/oauthlib/oauth2/rfc6749/request_validator.py
diff --git a/oauthlib/oauth2/rfc8628/clients/device.py b/oauthlib/oauth2/rfc8628/clients/device.py
diff --git a/oauthlib/openid/connect/core/endpoints/userinfo.py b/oauthlib/openid/connect/core/endpoints/userinfo.py

Original file line number	Diff line number	Diff line change
`@@ -2,7 +2,7 @@`
`2`	`2`	`#`
`3`	`3`
`4`	`4`	`# You can set these variables from the command line.`
`5`		`-SPHINXOPTS = -v`
	`5`	`+SPHINXOPTS = -v -W`
`6`	`6`	`SPHINXBUILD = sphinx-build`
`7`	`7`	`PAPER =`
`8`	`8`	`BUILDDIR = _build`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-OpenID Authorization Code`
	`1`	`+OpenID Refresh Grant`
`2`	`2`	`-------------------------`
`3`	`3`
`4`	`4`	`.. autoclass:: oauthlib.openid.connect.core.grant_types.RefreshTokenGrant`