Fixed Sphinx / sphinxcontrib-applehelp version issue

Details: * Docs: Increased minimum Sphinx versions to 7.1.0 on Python 3.8 and to 7.2.0 on Python >=3.9 and adjusted dependent package versions in order to fix a version incompatibility between sphinxcontrib-applehelp and Sphinx. Disabled Sphinx runs on Python <=3.7 in order to no longer having to deal with older Sphinx versions. (issue #444) Signed-off-by: Andreas Maier <[email protected]>
zhmcclient · Jan 14, 2024 · c31e989 · c31e989
1 parent 227dccd
commit c31e989
Show file tree

Hide file tree

Showing 5 changed files with 68 additions and 44 deletions.
diff --git a/Makefile b/Makefile
@@ -133,7 +133,15 @@ doc_dependent_files := \
 done_dir := done
 
 # Packages whose dependencies are checked using pip-missing-reqs
-check_reqs_packages := pip_check_reqs pipdeptree build pytest coverage coveralls flake8 pylint sphinx twine
+ifeq ($(python_version),3.6)
+  check_reqs_packages := pip_check_reqs pipdeptree build pytest coverage coveralls flake8 pylint twine
+else
+ifeq ($(python_version),3.7)
+  check_reqs_packages := pip_check_reqs pipdeptree build pytest coverage coveralls flake8 pylint twine
+else
+  check_reqs_packages := pip_check_reqs pipdeptree build pytest coverage coveralls flake8 pylint twine sphinx
+endif
+endif
 
 # Safety policy file
 safety_policy_file := .safety-policy.yml
@@ -332,10 +340,18 @@ $(done_dir)/develop_$(pymn)_$(PACKAGE_LEVEL).done: $(done_dir)/install_$(pymn)_$
 	@echo "Makefile: Done installing prerequisites for development"
 	echo "done" >$@
 
+# Boolean variable indicating that Sphinx should be run
+# We run Sphinx only on Python>=3.8 because lower Python versions require too old Sphinx versions
+run_sphinx := $(shell $(PYTHON_CMD) -c "import sys; py=sys.version_info[0:2]; sys.stdout.write('true' if py>=(3,8) else 'false')")
+
 $(doc_build_file): $(done_dir)/develop_$(pymn)_$(PACKAGE_LEVEL).done $(doc_dependent_files)
+ifeq ($(run_sphinx),true)
 	@echo "Makefile: Generating HTML documentation with main file: $@"
 	sphinx-build -b html -v $(doc_dir) $(doc_build_dir)
 	@echo "Makefile: Done generating HTML documentation"
+else
+	@echo "Makefile: Skipping Sphinx to generate HTML documentation on Python version $(python_version)"
+endif
 
 # Note: distutils depends on the right files specified in MANIFEST.in, even when
 # they are already specified e.g. in 'package_data' in setup.py.

diff --git a/dev-requirements.txt b/dev-requirements.txt
@@ -93,24 +93,28 @@ dill>=0.2; python_version <= '3.10'
 dill>=0.3.7; python_version >= '3.11'
 
 # Sphinx (no imports, invoked via sphinx-build script):
-# Keep in sync with rtd-requirements.txt
-# Sphinx 4.0.0 breaks autodocsumm and needs to be excluded
-# Sphinx <4.3.0 requires docutils <0.18 due to an incompatibility
-Sphinx>=3.5.4,!=4.0.0,<4.3.0; python_version <= '3.9'
-Sphinx>=4.2.0; python_version >= '3.10'
-docutils>=0.13.1,<0.17; python_version <= '3.9'
-docutils>=0.14,<0.17; python_version == '3.10'
-docutils>=0.16,<0.17; python_version >= '3.11'
-sphinx-git>=10.1.1
-GitPython>=2.1.1; python_version == '3.6'
-GitPython>=3.1.37; python_version >= '3.7'
-sphinxcontrib-fulltoc>=1.2.0
-sphinxcontrib-websupport>=1.1.2
-Pygments>=2.7.4; python_version == '3.6'
-Pygments>=2.15.0; python_version >= '3.7'
-sphinx-rtd-theme>=1.0.0
-# Babel 2.7.0 fixes an ImportError for MutableMapping which starts failing on Python 3.10
-Babel>=2.9.1
+# Sphinx 6.0.0 started requiring Python>=3.8
+# Sphinx 7.2.0 started requiring Python>=3.9
+# Sphinx is used only on Python>=3.8
+Sphinx>=7.1.0; python_version == '3.8'
+Sphinx>=7.2.0; python_version >= '3.9'
+# Sphinx 7.1.0 pins docutils to <0.21
+docutils>=0.18.1,<0.21; python_version == '3.8'
+sphinx-git>=10.1.1; python_version >= '3.8'
+GitPython>=3.1.37; python_version >= '3.8'
+Pygments>=2.15.0; python_version >= '3.8'
+sphinx-rtd-theme>=2.0.0; python_version >= '3.8'
+sphinxcontrib-applehelp>=1.0.4; python_version >= '3.8'
+sphinxcontrib-devhelp>=1.0.2; python_version >= '3.8'
+sphinxcontrib-htmlhelp>=2.0.1; python_version >= '3.8'
+sphinxcontrib-jquery>=4.1; python_version >= '3.8'
+sphinxcontrib-jsmath>=1.0.1; python_version >= '3.8'
+sphinxcontrib-qthelp>=1.0.3; python_version >= '3.8'
+sphinxcontrib-serializinghtml>=1.1.5; python_version == '3.8'
+sphinxcontrib-serializinghtml>=1.1.9; python_version >= '3.9'
+sphinxcontrib-websupport>=1.2.4; python_version >= '3.8'
+autodocsumm>=0.2.12; python_version >= '3.8'
+Babel>=2.9.1; python_version >= '3.8'
 
 # Twine (no imports, invoked via twine script):
 twine>=3.0.0

diff --git a/docs/changes.rst b/docs/changes.rst
@@ -28,6 +28,12 @@ Released: not yet
 
 **Bug fixes:**
 
+* Docs: Increased minimum Sphinx versions to 7.1.0 on Python 3.8 and to 7.2.0 on
+  Python >=3.9 and adjusted dependent package versions in order to fix a version
+  incompatibility between sphinxcontrib-applehelp and Sphinx.
+  Disabled Sphinx runs on Python <=3.7 in order to no longer having to deal
+  with older Sphinx versions. (issue #444)
+
 **Enhancements:**
 
 **Cleanup:**

diff --git a/minimum-constraints.txt b/minimum-constraints.txt
@@ -48,7 +48,7 @@ urllib3==1.26.18
 jsonschema==3.2.0
 six==1.14.0; python_version <= '3.9'
 six==1.16.0; python_version >= '3.10'
-Jinja2==2.11.3
+Jinja2==3.0.0
 # PyYAML is also used by dparse
 PyYAML==5.3.1
 
@@ -67,7 +67,7 @@ decorator==4.0.11
 docopt==0.6.2
 idna==2.5
 immutable-views==0.6.0
-MarkupSafe==1.1.0
+MarkupSafe==2.0.0
 pytz==2016.10; python_version <= '3.9'
 pytz==2019.1; python_version >= '3.10'
 requests==2.25.0; python_version == '3.6'
@@ -142,19 +142,24 @@ dill==0.2; python_version <= '3.10'
 dill==0.3.7; python_version >= '3.11'
 
 # Sphinx (no imports, invoked via sphinx-build script):
-Sphinx==3.5.4; python_version <= '3.9'
-Sphinx==4.2.0; python_version >= '3.10'
-docutils==0.13.1; python_version <= '3.9'
-docutils==0.14; python_version == '3.10'
-docutils==0.16; python_version >= '3.11'
-sphinx-git==10.1.1
-GitPython==2.1.1; python_version == '3.6'
-GitPython==3.1.37; python_version >= '3.7'
-sphinxcontrib-websupport==1.1.2
-Pygments==2.7.4; python_version == '3.6'
-Pygments==2.15.0; python_version >= '3.7'
-sphinx-rtd-theme==1.0.0
-Babel==2.9.1
+Sphinx==7.1.0; python_version == '3.8'
+Sphinx==7.2.0; python_version >= '3.9'
+docutils==0.18.1; python_version >= '3.8'
+sphinx-git==10.1.1; python_version >= '3.8'
+GitPython==3.1.37; python_version >= '3.8'
+Pygments==2.15.0; python_version >= '3.8'
+sphinx-rtd-theme==2.0.0; python_version >= '3.8'
+sphinxcontrib-applehelp==1.0.4; python_version >= '3.8'
+sphinxcontrib-devhelp==1.0.2; python_version >= '3.8'
+sphinxcontrib-htmlhelp==2.0.1; python_version >= '3.8'
+sphinxcontrib-jquery==4.1; python_version >= '3.8'
+sphinxcontrib-jsmath==1.0.1; python_version >= '3.8'
+sphinxcontrib-qthelp==1.0.3; python_version >= '3.8'
+sphinxcontrib-serializinghtml==1.1.5; python_version == '3.8'
+sphinxcontrib-serializinghtml==1.1.9; python_version >= '3.9'
+sphinxcontrib-websupport==1.2.4; python_version >= '3.8'
+autodocsumm==0.2.12; python_version >= '3.8'
+Babel==2.9.1; python_version >= '3.8'
 
 # Twine (no imports, invoked via twine script):
 # readme-renderer (used by twine, uses Pygments)
@@ -183,7 +188,7 @@ contextlib2==0.6.0
 gitdb2==2.0.0; python_version == '3.6'
 gitdb==4.0.8
 html5lib==1.0.1  # used with minimum package levels
-imagesize==0.7.1
+imagesize==1.3.0
 iniconfig==1.1.1; python_version >= "3.6"  # used by pytest since its 6.0.0 which requires py36
 keyring==18.0.0
 more-itertools==8.0.0  # used with minimum package levels
@@ -195,14 +200,7 @@ pyproject-hooks==1.0.0; python_version >= '3.7'
 requests-toolbelt==0.8.0
 rfc3986==1.4.0; python_version >= "3.6"  # used by twine since its 3.2.0 which requires py36
 smmap==3.0.1
-sphinxcontrib-applehelp==1.0.2
-sphinxcontrib-devhelp==1.0.2
-sphinxcontrib-htmlhelp==1.0.3; python_version <= '3.9'
-sphinxcontrib-htmlhelp==2.0.0; python_version >= '3.10'
-sphinxcontrib-jsmath==1.0.1
-sphinxcontrib-serializinghtml==1.1.5
-sphinxcontrib-qthelp==1.0.3
-snowballstemmer==1.2.1
+snowballstemmer==2.0.0
 toml==0.10.0  # used by pylint and pytest since some version
 tomli==1.1.0; python_version >= '3.7' and python_version <= '3.10'
 tqdm==4.28.1

diff --git a/requirements.txt b/requirements.txt
@@ -16,7 +16,7 @@ prometheus-client>=0.19.0; python_version >= '3.8'
 
 urllib3>=1.25.18
 jsonschema>=3.2.0
-Jinja2>=2.11.3
+Jinja2>=3.0.0
 
 # PyYAML 5.3.x has wheel archives for Python 2.7, 3.5 - 3.9
 # PyYAML 5.4.x has wheel archives for Python 2.7, 3.6 - 3.9