docs: refresh conf.py for readability

docs/Makefile

@@ -63,6 +63,9 @@ scopes: source/rbac/scope-table.md
 source/rbac/scope-table.md: source/rbac/generate-scope-table.py
 	python3 source/rbac/generate-scope-table.py
 
+# If the pre-requisites for the html target is updated, also update the Read The
+# Docs section in docs/source/conf.py.
+#
 html: metrics scopes
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo

docs/requirements.txt

@@ -14,6 +14,6 @@ pre-commit
 pydata-sphinx-theme
 pytablewriter>=0.56
 ruamel.yaml
-sphinx>=1.7
+sphinx>=4
 sphinx-copybutton
 sphinx-jsonschema

docs/source/conf.py

@@ -1,59 +1,68 @@
+# Configuration file for Sphinx to build our documentation to HTML.
 #
+# Configuration reference: https://www.sphinx-doc.org/en/master/usage/configuration.html
+#
+import contextlib
+import datetime
+import io
 import os
-
+import subprocess
-# -- General configuration ------------------------------------------------
-
-# Sphinx extension modules
-extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.napoleon',
-    'autodoc_traits',
-    'sphinx_copybutton',
-    'sphinx-jsonschema',
-    'myst_parser',
-]
-
-myst_heading_anchors = 2
-myst_enable_extensions = [
-    'colon_fence',
-    'deflist',
-]
-# The master toctree document.
-root_doc = master_doc = 'index'
-
-# General information about the project.
-project = 'JupyterHub'
-copyright = '2016, Project Jupyter team'
-author = 'Project Jupyter team'
-
-# Autopopulate version
-import jupyterhub
-
-# The short X.Y version.
-version = '%i.%i' % jupyterhub.version_info[:2]
-# The full version, including alpha/beta/rc tags.
-release = jupyterhub.__version__
-
-language = "en"
-exclude_patterns = []
-pygments_style = 'sphinx'
-todo_include_todos = False
-
-# Set the default role so we can use `foo` instead of ``foo``
-default_role = 'literal'
-
-from contextlib import redirect_stdout
-from io import StringIO
 
 from docutils import nodes
 from sphinx.directives.other import SphinxDirective
 
-# -- Config -------------------------------------------------------------
+import jupyterhub
 from jupyterhub.app import JupyterHub
 
-# create a temp instance of JupyterHub just to get the output of the generate-config
+# -- Project information -----------------------------------------------------
-# and help --all commands.
+# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+#
+project = "JupyterHub"
+author = "Project Jupyter Contributors"
+copyright = f"{datetime.date.today().year}, {author}"
+version = "%i.%i" % jupyterhub.version_info[:2]
+release = jupyterhub.__version__
+
+
+# -- General Sphinx configuration --------------------------------------------
+# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+#
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "autodoc_traits",
+    "sphinx_copybutton",
+    "sphinx-jsonschema",
+    "myst_parser",
+]
+root_doc = "index"
+source_suffix = [".md", ".rst"]
+# default_role let's use use `foo` instead of ``foo`` in rST
+default_role = "literal"
+
+
+# -- MyST configuration ------------------------------------------------------
+# ref: https://myst-parser.readthedocs.io/en/latest/configuration.html
+#
+myst_heading_anchors = 2
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+]
+
+
+# -- Custom directives to generate documentation -----------------------------
+# ref: https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html
+#
+# We define custom directives to help us generate documentation using Python on
+# demand when referenced from our documentation files.
+#
+
+# Create a temp instance of JupyterHub for use by two separate directive classes
+# to get the output from using the "--generate-config" and "--help-all" CLI
+# flags respectively.
+#
 jupyterhub_app = JupyterHub()
 
 
@@ -70,8 +79,8 @@ class ConfigDirective(SphinxDirective):
         # The generated configuration file for this version
         generated_config = jupyterhub_app.generate_config_file()
         # post-process output
-        home_dir = os.environ['HOME']
+        home_dir = os.environ["HOME"]
-        generated_config = generated_config.replace(home_dir, '$HOME', 1)
+        generated_config = generated_config.replace(home_dir, "$HOME", 1)
         par = nodes.literal_block(text=generated_config)
         return [par]
 
@@ -87,36 +96,55 @@ class HelpAllDirective(SphinxDirective):
 
     def run(self):
         # The output of the help command for this version
-        buffer = StringIO()
+        buffer = io.StringIO()
-        with redirect_stdout(buffer):
+        with contextlib.redirect_stdout(buffer):
-            jupyterhub_app.print_help('--help-all')
+            jupyterhub_app.print_help("--help-all")
         all_help = buffer.getvalue()
         # post-process output
-        home_dir = os.environ['HOME']
+        home_dir = os.environ["HOME"]
-        all_help = all_help.replace(home_dir, '$HOME', 1)
+        all_help = all_help.replace(home_dir, "$HOME", 1)
         par = nodes.literal_block(text=all_help)
         return [par]
 
 
 def setup(app):
-    app.add_css_file('custom.css')
+    app.add_css_file("custom.css")
-    app.add_directive('jupyterhub-generate-config', ConfigDirective)
+    app.add_directive("jupyterhub-generate-config", ConfigDirective)
-    app.add_directive('jupyterhub-help-all', HelpAllDirective)
+    app.add_directive("jupyterhub-help-all", HelpAllDirective)
 
 
-source_suffix = ['.rst', '.md']
+# -- Read The Docs -----------------------------------------------------------
+#
+# Since RTD runs sphinx-build directly without running "make html", we run the
+# pre-requisite steps for "make html" from here if needed.
+#
+if os.environ.get("READTHEDOCS"):
+    docs = os.path.dirname(os.path.dirname(__file__))
+    subprocess.check_call(["make", "metrics", "scopes"], cwd=docs)
 
-# -- Options for HTML output ----------------------------------------------
 
-# The theme to use for HTML
+# -- Spell checking ----------------------------------------------------------
-html_theme = 'pydata_sphinx_theme'
+# ref: https://sphinxcontrib-spelling.readthedocs.io/en/latest/customize.html#configuration-options
+#
+# The "sphinxcontrib.spelling" extension is optionally enabled if its available.
+#
+try:
+    import sphinxcontrib.spelling  # noqa
+except ImportError:
+    pass
+else:
+    extensions.append("sphinxcontrib.spelling")
+spelling_word_list_filename = "spelling_wordlist.txt"
 
-html_logo = '_static/images/logo/logo.png'
-html_favicon = '_static/images/logo/favicon.ico'
 
-# Paths that contain custom static files (such as style sheets)
+# -- Options for HTML output -------------------------------------------------
-html_static_path = ['_static']
+# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+#
+html_logo = "_static/images/logo/logo.png"
+html_favicon = "_static/images/logo/favicon.ico"
+html_static_path = ["_static"]
 
+html_theme = "pydata_sphinx_theme"
 html_theme_options = {
     "icon_links": [
         {
@@ -133,40 +161,34 @@ html_theme_options = {
     "use_edit_page_button": True,
     "navbar_align": "left",
 }
-
 html_context = {
     "github_user": "jupyterhub",
     "github_repo": "jupyterhub",
     "github_version": "main",
-    "doc_path": "docs",
+    "doc_path": "docs/source",
 }
 
-# -- Intersphinx ----------------------------------------------------------
 
+# -- Options for linkcheck builder -------------------------------------------
+# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder
+#
+linkcheck_ignore = [
+    r"(.*)github\.com(.*)#",  # javascript based anchors
+    r"(.*)/#%21(.*)/(.*)",  # /#!forum/jupyter - encoded anchor edge case
+    r"https://github.com/[^/]*$",  # too many github usernames / searches in changelog
+    "https://github.com/jupyterhub/jupyterhub/pull/",  # too many PRs in changelog
+    "https://github.com/jupyterhub/jupyterhub/compare/",  # too many comparisons in changelog
+]
+linkcheck_anchors_ignore = [
+    "/#!",
+    "/#%21",
+]
+
+
+# -- Intersphinx -------------------------------------------------------------
+# ref: https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
+#
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/3/', None),
+    "python": ("https://docs.python.org/3/", None),
-    'tornado': ('https://www.tornadoweb.org/en/stable/', None),
+    "tornado": ("https://www.tornadoweb.org/en/stable/", None),
 }
-
-# -- Read The Docs --------------------------------------------------------
-
-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
-if on_rtd:
-    # readthedocs.org uses their theme by default, so no need to specify it
-    # build both metrics and rest-api, since RTD doesn't run make
-    from os.path import dirname
-    from subprocess import check_call as sh
-
-    docs = dirname(dirname(__file__))
-    sh(['make', 'metrics', 'scopes'], cwd=docs)
-
-# -- Spell checking -------------------------------------------------------
-
-try:
-    import sphinxcontrib.spelling  # noqa
-except ImportError:
-    pass
-else:
-    extensions.append("sphinxcontrib.spelling")
-
-spelling_word_list_filename = 'spelling_wordlist.txt'