docs: configure intersphinx and update another helpstring

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
 #

oauthenticator/oauth2.py

@@ -517,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:
-
-        `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
-
-        Note that some of these are dependent on the httpclient implementation.
+        .. code-block:: python
+
+            # Example: send requests through a proxy
+            c.OAuthenticator.http_request_kwargs = {
+                "proxy_host": "proxy.example.com",
+                "proxy_port": 8080,
+            }
+
+            # Example: validate against certain root certificates
+            c.OAuthenticator.http_request_kwargs = {
+                "ca_certs": "/run/secrets/kubernetes.io/serviceaccount/ca.crt",
+            }
+
+        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`.
         """,
     )