Fix documentation build configuration

- Add html_context with versions list to prevent KeyError in Pallets theme
- Configure html_theme_options with globaltoc_maxdepth to fix 404 page rendering
- Upgrade Sphinx and documentation dependencies to latest versions
- Resolves build failures on ReadTheDocs
- Build docs on Ubuntu 24.04 and Python 3.12

Author: jugmac00

.readthedocs.yaml

@@ -1,8 +1,8 @@
 version: 2
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    python: "3.11"
+    python: "3.12"
 python:
   install:
     - requirements: docs/requirements.txt
@@ -11,3 +11,4 @@ python:
 sphinx:
   builder: dirhtml
   fail_on_warning: true
+  configuration: docs/conf.py

CHANGES.rst

@@ -4,6 +4,7 @@ Changelog
 1.4.1 (unreleased)
 ------------------
 - migrate from setup.py to pyproject.toml configuration
+- fix doc building on read the docs
 
 1.4.0 (2023.10.03)
 ------------------

docs/conf.py

@@ -35,6 +35,16 @@
 # a list of builtin themes.
 html_theme = 'flask'
 
+# Theme options for the Pallets Flask theme
+html_theme_options = {
+    'globaltoc_maxdepth': 2,
+}
+
+# Context for the theme
+html_context = {
+    'versions': [],
+}
+
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 # html_title = None

docs/requirements.in

@@ -1,3 +1,3 @@
 Sphinx
 Pallets-Sphinx-Themes
-packaging < 22  # https://github.com/readthedocs/readthedocs.org/issues/9805
+packaging

docs/requirements.txt

@@ -1,62 +1,60 @@
 #
-# This file is autogenerated by pip-compile with Python 3.11
+# This file is autogenerated by pip-compile with Python 3.12
 # by the following command:
 #
-#    pip-compile --output-file=/home/jugmac00/Projects/flask-reuploaded/docs/requirements.txt /home/jugmac00/Projects/flask-reuploaded/docs/requirements.in
+#    pip-compile --output-file=/home/juergen.gmach@canonical.com/src/flask-reuploaded/docs/requirements.txt /home/juergen.gmach@canonical.com/src/flask-reuploaded/docs/requirements.in
 #
-alabaster==0.7.13
+alabaster==1.0.0
     # via sphinx
-babel==2.13.0
+babel==2.18.0
     # via sphinx
-certifi==2023.7.22
+certifi==2026.1.4
     # via requests
-charset-normalizer==3.3.0
+charset-normalizer==3.4.4
     # via requests
-docutils==0.20.1
+docutils==0.22.4
     # via sphinx
-idna==3.4
+idna==3.11
     # via requests
 imagesize==1.4.1
     # via sphinx
-jinja2==3.1.2
+jinja2==3.1.6
     # via sphinx
-markupsafe==2.1.3
+markupsafe==3.0.3
     # via jinja2
-packaging==21.3
+packaging==26.0
     # via
-    #   -r /home/jugmac00/Projects/flask-reuploaded/docs/requirements.in
+    #   -r /home/juergen.gmach@canonical.com/src/flask-reuploaded/docs/requirements.in
     #   pallets-sphinx-themes
     #   sphinx
-pallets-sphinx-themes==2.1.1
-    # via -r /home/jugmac00/Projects/flask-reuploaded/docs/requirements.in
-pygments==2.16.1
+pallets-sphinx-themes==2.3.0
+    # via -r /home/juergen.gmach@canonical.com/src/flask-reuploaded/docs/requirements.in
+pygments==2.19.2
     # via sphinx
-pyparsing==3.1.1
-    # via packaging
-requests==2.31.0
+requests==2.32.5
     # via sphinx
-snowballstemmer==2.2.0
+roman-numerals==4.1.0
     # via sphinx
-sphinx==7.2.6
+snowballstemmer==3.0.1
+    # via sphinx
+sphinx==9.1.0
     # via
-    #   -r /home/jugmac00/Projects/flask-reuploaded/docs/requirements.in
+    #   -r /home/juergen.gmach@canonical.com/src/flask-reuploaded/docs/requirements.in
     #   pallets-sphinx-themes
-    #   sphinxcontrib-applehelp
-    #   sphinxcontrib-devhelp
-    #   sphinxcontrib-htmlhelp
-    #   sphinxcontrib-qthelp
-    #   sphinxcontrib-serializinghtml
-sphinxcontrib-applehelp==1.0.7
+    #   sphinx-notfound-page
+sphinx-notfound-page==1.1.0
+    # via pallets-sphinx-themes
+sphinxcontrib-applehelp==2.0.0
     # via sphinx
-sphinxcontrib-devhelp==1.0.5
+sphinxcontrib-devhelp==2.0.0
     # via sphinx
-sphinxcontrib-htmlhelp==2.0.4
+sphinxcontrib-htmlhelp==2.1.0
     # via sphinx
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
-sphinxcontrib-qthelp==1.0.6
+sphinxcontrib-qthelp==2.0.0
     # via sphinx
-sphinxcontrib-serializinghtml==1.1.9
+sphinxcontrib-serializinghtml==2.0.0
     # via sphinx
-urllib3==2.0.6
+urllib3==2.6.3
     # via requests