Merge pull request #637 from consideRatio/pr/update-docs-further

docs: coalesce v16 upgrade page into changelog, improve helpstrings

docs/source/conf.py

@@ -107,7 +107,7 @@ def setup(app):
         app.add_directive("versionremoved", VersionChange)
 
 
-# -- General Sphinx configuration ---------------------------------------------------
+# -- General Sphinx configuration --------------------------------------------
 # ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 #
 extensions = [
@@ -134,6 +134,29 @@ def setup(app):
 autosummary_generate = False
 
 
+# -- Options for intersphinx extension ---------------------------------------
+# ref: https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
+#
+# The extension makes us able to link like to other projects like below.
+#
+#     rST  - :external:py:class:`tornado.httpclient.AsyncHTTPClient`
+#     MyST - {external:py:class}`tornado.httpclient.AsyncHTTPClient`
+#
+# To see what we can link to, do the following where "objects.inv" is appended
+# to the sphinx based website:
+#
+#     python -m sphinx.ext.intersphinx https://www.tornadoweb.org/en/stable/objects.inv
+#
+intersphinx_mapping = {
+    "tornado": ("https://www.tornadoweb.org/en/stable/", None),
+    "jupyterhub": ("https://jupyterhub.readthedocs.io/en/stable/", None),
+}
+
+# intersphinx_disabled_reftypes set based on recommendation in
+# https://docs.readthedocs.io/en/stable/guides/intersphinx.html#using-intersphinx
+intersphinx_disabled_reftypes = ["*"]
+
+
 # -- Options for HTML output -------------------------------------------------
 # ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 #

docs/source/index.md

@@ -34,10 +34,9 @@ Things like how to write your own `oauthenticator` or how to migrate to a newer
 :maxdepth: 1
 :caption: How-to guides
 
-how-to/migrations/upgrade-to-15
-how-to/migrations/upgrade-to-16
 how-to/custom-403
 how-to/writing-an-oauthenticator
+how-to/migrations/upgrade-to-15
 ```
 
 ## Topic guides

docs/source/reference/changelog.md

@@ -8,6 +8,7 @@ command line for details.
 
 ### Breaking changes
 
+- Support for Python 3.7 has been dropped, Python 3.8+ is now required.
 - [All] Users are now authorized based on _either_ being part of
   {attr}`.OAuthenticator.admin_users`, {attr}`.OAuthenticator.allowed_users`, an
   Authenticator specific allowed group/team/organization, or if by being part of
@@ -31,6 +32,32 @@ command line for details.
 - [CILogon] {attr}`.CILogonOAuthenticator.allowed_idps` is now required config,
   and `shown_idps`, `username_claim`, `additional_username_claims` must no
   longer be configured.
+- [Okpy] The public functions `OkpyOAuthenticator.get_auth_request` and
+  `OkpyOAuthenticator.get_user_info_request` were removed.
+
+### Deprecations
+
+- [Generic, Auth0] `username_key` is deprecated and is replaced by
+  {attr}`.OAuthenticator.username_claim`.
+- [Generic] {attr}`.GenericOAuthenticator.extra_params` is deprecated and is
+  replaced by {attr}`.OAuthenticator.token_params`.
+
+### Highlights
+
+- [All] The project has been refactored greatly to make it easier to use,
+  understand, and maintain code and documentation.
+
+- [All] {attr}`.OAuthenticator.refresh_pre_spawn` is now by default enabled if
+  {attr}`.OAuthenticator.enable_auth_state` is enabled.
+
+- [All] Low level configuration in `GenericOAuthenticator` has been moved to
+  the common base class `OAuthenticator` and is therefore available to all
+  authenticators.
+
+  - {attr}`.OAuthenticator.basic_auth`
+  - {attr}`.OAuthenticator.token_params`
+  - {attr}`.OAuthenticator.userdata_params`
+  - {attr}`.OAuthenticator.userdata_token_method`
 
 (changelog:version-15)=
 

oauthenticator/oauth2.py

@@ -302,7 +302,16 @@ class OAuthenticator(Authenticator):
     authorize_url = Unicode(
         config=True,
         help="""
-        The authenticate url for initiating oauth
+        The URL to where the user is to be redirected initially based on the
+        OAuth2 protocol. The user will be redirected back with an
+        `authorization grant code`_ after authenticating successfully with the
+        identity provider.
+
+        .. _authorization grant code: https://www.rfc-editor.org/rfc/rfc6749#section-1.3.1
+
+        For more context, see the `Protocol Flow section
+        <https://www.rfc-editor.org/rfc/rfc6749#section-1.2>`_ in the OAuth2
+        standard document, specifically steps A-B.
         """,
     )
 
@@ -313,7 +322,15 @@ def _authorize_url_default(self):
     token_url = Unicode(
         config=True,
         help="""
-        The url retrieving an access token at the completion of oauth
+        The URL to where this authenticator makes a request to acquire an
+        `access token`_ based on the authorization code received by the user
+        returning from the :attr:`authorize_url`.
+
+        .. _access token: https://www.rfc-editor.org/rfc/rfc6749#section-1.4
+
+        For more context, see the `Protocol Flow section
+        <https://www.rfc-editor.org/rfc/rfc6749#section-1.2>`_ in the OAuth2
+        standard document, specifically steps C-D.
         """,
     )
 
@@ -324,7 +341,13 @@ def _token_url_default(self):
     userdata_url = Unicode(
         config=True,
         help="""
-        The url for retrieving user data with a completed access token
+        The URL to where this authenticator makes a request to acquire user
+        details with an access token received via a request to the
+        :attr:`token_url`.
+
+        For more context, see the `Protocol Flow section
+        <https://www.rfc-editor.org/rfc/rfc6749#section-1.2>`_ in the OAuth2
+        standard document, specifically steps E-F.
         """,
     )
 
@@ -336,8 +359,8 @@ def _userdata_url_default(self):
         "username",
         config=True,
         help="""
-        Field in userdata reply to use for username The field in the userdata
-        response from which to get the JupyterHub username.
+        The key to get the JupyterHub username from in the data response to the
+        request made to :attr:`userdata_url`.
 
         Examples include: email, username, nickname
 
@@ -494,14 +517,22 @@ def _validate_server_cert_default(self):
         help="""
         Extra default kwargs passed to all HTTPRequests.
 
-        For example, to use a HTTP proxy for all requests:
+        .. code-block:: python
 
-        `c.OAuthenticator.http_request_kwargs = {"proxy_host": "proxy.example.com", "proxy_port": 8080}`
+            # Example: send requests through a proxy
+            c.OAuthenticator.http_request_kwargs = {
+                "proxy_host": "proxy.example.com",
+                "proxy_port": 8080,
+            }
 
-        See the `tornado.httpclient.HTTPRequest` documentation for all options and limitations:
-        https://www.tornadoweb.org/en/stable/httpclient.html#tornado.httpclient.HTTPRequest
+            # Example: validate against certain root certificates
+            c.OAuthenticator.http_request_kwargs = {
+                "ca_certs": "/path/to/a.crt",
+            }
 
-        Note that some of these are dependent on the httpclient implementation.
+        See :external:py:class:`tornado.httpclient.HTTPRequest` for all kwargs
+        options you can pass. Note that the HTTP client making these requests is
+        :external:py:class:`tornado.httpclient.AsyncHTTPClient`.
         """,
     )
 

oauthenticator/openshift.py

@@ -86,6 +86,14 @@ def _ca_certs_default(self):
         help="""
         Used to determine the default values for `authorize_url` and
         `token_url`.
+
+        By default, this is determined on startup by a request to the
+        `openshift_url` appended with "/.well-known/oauth-authorization-server",
+        where "issuer" is extracted from the response.
+
+        For more context, see the `Obtaining Authorization Server Metadata
+        section <https://datatracker.ietf.org/doc/html/rfc8414#section-3>`_ in
+        an OAuth2 standard document.
         """,
     )