From 6d2dbcef386c462857104cae4f1e1dbccb932e23 Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.i.sundell@gmail.com>
Date: Sun, 22 Sep 2024 17:24:07 +0200
Subject: [PATCH] Refresh sphinx config file and resolve failure in sphinx 8

---
 docs/requirements.txt |   1 +
 docs/source/conf.py   | 152 +++++++++++++++++++++++-------------------
 2 files changed, 84 insertions(+), 69 deletions(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index ca40926a..d78cb3a4 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -10,3 +10,4 @@ autodoc-traits
 myst-parser>=0.17.0
 sphinx-book-theme
 sphinx-copybutton
+sphinxext-rediraffe
diff --git a/docs/source/conf.py b/docs/source/conf.py
index c02aa41a..c899ccd5 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -1,69 +1,40 @@
-import os
-import sys
-from os.path import dirname
-
-# For conversion from markdown to html
-# set paths
-docs = dirname(dirname(__file__))
-root = dirname(docs)
-sys.path.insert(0, root)
-sys.path.insert(0, os.path.join(docs, 'sphinxext'))
-
-# -- General configuration ------------------------------------------------
+# Configuration file for Sphinx to build our documentation to HTML.
+#
+# Configuration reference: https://www.sphinx-doc.org/en/master/usage/configuration.html
+#
+import datetime
+
+import kubespawner
+
+# -- Project information -----------------------------------------------------
+# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+#
+project = "KubeSpawner"
+copyright = f"{datetime.date.today().year}, Project Jupyter Contributors"
+author = "Project Jupyter Contributors"
+version = "%i.%i" % kubespawner.version_info[:2]
+release = kubespawner.__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',
+    'sphinxext.rediraffe',
     'autodoc_traits',
     'myst_parser',
 ]
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# Set the default role so we can use `foo` instead of ``foo``
-default_role = 'literal'
-
-# source_suffix = ['.rst', '.md']
-source_suffix = ['.rst', '.md']
-
-# The root toctree document.
-root_doc = master_doc = 'index'
+root_doc = "index"
+source_suffix = [".md", ".rst"]
 
-# General information about the project.
-project = 'kubespawner'
-copyright = '2021, Project Jupyter'
-author = 'Project Jupyter'
-
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-import pkg_resources
-
-# The full version, including alpha/beta/rc tags.
-release = pkg_resources.get_distribution("jupyterhub-kubespawner").version
-# The short X.Y version.
-version = '.'.join(release.split('.')[:2])
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['build', 'Thumbs.db', '.DS_Store']
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
+# default_role is set for use with reStructuredText that we still need to use in
+# docstrings in the autodoc_traits inspected Python module. It makes single
+# backticks around text, like `my_function`, behave as in typical Markdown.
+default_role = "literal"
 
 
 # -- MyST configuration ------------------------------------------------------
@@ -75,18 +46,11 @@
 ]
 
 
-# -- Options for HTML output ----------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
+# -- Options for HTML output -------------------------------------------------
+# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 #
-html_theme = 'sphinx_book_theme'
 html_title = "Kubespawner"
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#
+html_theme = "sphinx_book_theme"
 html_theme_options = {
     "repository_url": "https://github.com/jupyterhub/kubespawner",
     "use_issues_button": True,
@@ -100,5 +64,55 @@
 html_static_path = ['_static']
 
 
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+# -- 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:`jupyterhub.spawner.Spawner`
+#     MyST - {external:py:class}`jupyterhub.spawner.Spawner`
+#
+# 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://jupyterhub.readthedocs.io/en/stable/objects.inv
+#
+intersphinx_mapping = {
+    "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 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/kubespawner/pull/",  # too many pull requests in changelog
+    "https://github.com/jupyterhub/kubespawner/compare/",  # too many ref comparisons in changelog
+]
+linkcheck_anchors_ignore = [
+    "/#!",
+    "/#%21",
+]
+
+
+# -- Options for the rediraffe extension -------------------------------------
+# ref: https://github.com/wpilibsuite/sphinxext-rediraffe#readme
+#
+# This extensions help us relocated content without breaking links. If a
+# document is moved internally, put its path as a dictionary key in the
+# redirects dictionary below and its new location in the value.
+#
+# If the changelog has been moved to live under reference/, then you'd add this
+# entry to the rediraffe_redirects dictionary:
+#
+#   "changelog": "reference/changelog",
+#
+rediraffe_branch = "main"
+rediraffe_redirects = {}