From c12b694ce3695767c1b794d457e5a0baf0f58b29 Mon Sep 17 00:00:00 2001 From: Maxim Prokhorov Date: Mon, 10 Mar 2025 23:50:12 +0300 Subject: [PATCH] Fix sphinx v8 builds 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 --- .github/workflows/documentation.yml | 7 +++++-- doc/Makefile | 2 +- doc/conf.py | 6 +----- doc/requirements.txt | 14 ++++++-------- tests/ci/build_docs.sh | 2 +- 5 files changed, 14 insertions(+), 17 deletions(-) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index a7c72a0c41..977570aad8 100644 --- a/.github/workflows/documentation.yml +++ b/.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 diff --git a/doc/Makefile b/doc/Makefile index cbfd6af2ab..61d3e40b3c 100644 --- a/doc/Makefile +++ b/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 = . diff --git a/doc/conf.py b/doc/conf.py index 958f3cdbd0..0eef82bc24 100644 --- a/doc/conf.py +++ b/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()] - - diff --git a/doc/requirements.txt b/doc/requirements.txt index 8d90d8f59a..6b2684762d 100644 --- a/doc/requirements.txt +++ b/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 diff --git a/tests/ci/build_docs.sh b/tests/ci/build_docs.sh index b26852e553..7a5ae2a632 100755 --- a/tests/ci/build_docs.sh +++ b/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