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

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 @@ language = 'en'
 # 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 @@ linkcheck_anchors_ignore = ["/#!"]
 #
 # 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