Docs - fix sphinx v8 builds (#9235)

abnormal version selection w/ nbsphinx causing us to fall down to 5.x.x
venv install specific versions, fix arguments provided to the sphinx-build

Author: mcspr

.github/workflows/documentation.yml

@@ -24,5 +24,8 @@ jobs:
         python-version: '3.x'
     - name: Build documentation
       run: |
-        pip install --user -r doc/requirements.txt
-        bash ./tests/ci/build_docs.sh
+        pushd doc/
+        python3 -mvenv _venv
+        ./_venv/bin/pip install -r requirements.txt
+        env SPHINXBUILD=$(pwd)/_venv/bin/sphinx-build ../tests/ci/build_docs.sh
+        popd

doc/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -W --keep-going -n
+SPHINXOPTS    = --fail-on-warning --nitpicky
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = ESP8266ArduinoCore
 SOURCEDIR     = .

doc/conf.py

@@ -71,7 +71,7 @@
 # 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']
+exclude_patterns = ['_venv', '_build', 'Thumbs.db', '.DS_Store']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -162,11 +162,7 @@
 #
 # on_rtd is whether we are on readthedocs.org
 env_readthedocs = os.environ.get('READTHEDOCS', None)
-print(env_readthedocs)
 
 if not env_readthedocs:  # only import and set the theme if we're building docs locally
     import sphinx_rtd_theme
     html_theme = 'sphinx_rtd_theme'
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-
-

doc/requirements.txt

@@ -1,10 +1,8 @@
 # Requirements file for pip
 # list of Python packages used in documentation build
-sphinx
-sphinx-rtd-theme
-breathe
-nbsphinx
-docutils<0.17
-testresources
-#at the time of writing, requirement is pygments<3,>=2.4.1
-pygments>=2.4.1
+sphinx>=8.1.2,<9.0.0
+sphinx-rtd-theme>=3.0.2,<4.0.0
+breathe>=4.36.0,<5.0.0
+nbsphinx>=0.9.7,<1.0.0
+testresources>=2.0.1,<3.0.0
+pygments>=2.19.1,<3.0.0

tests/ci/build_docs.sh

@@ -5,4 +5,4 @@
 set -ev
 
 root=$(git rev-parse --show-toplevel)
-env SPHINXOPTS="-W" make -C $root/doc html
+make SPHINXOPTS="--fail-on-warning" SPHINXBUILD="${SPHINXBUILD:?sphinx-build}" -C $root/doc html