Skip to content

Commit

Permalink
Fixed Sphinx / sphinxcontrib-applehelp version issue
Browse files Browse the repository at this point in the history 
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 #547)

* Test: Added Python 3.8 with latest package levels to normal tests because
  that is now the minimum version to run Sphinx. (related to issue #547)

Signed-off-by: Andreas Maier <[email protected]>
  • Loading branch information
@andy-maier
andy-maier committed Jan 14, 2024
1 parent 528986d commit 3863763
Show file tree
Hide file tree
Showing 5 changed files with 107 additions and 64 deletions.
5 changes: 5 additions & 0 deletions .github/workflows/test.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,11 @@ jobs:
\"python-version\": \"3.6\", \
\"package_level\": \"minimum\" \
}, \
{ \
\"os\": \"ubuntu-latest\", \
\"python-version\": \"3.8\", \
\"package_level\": \"latest\" \
}, \
{ \
\"os\": \"macos-latest\", \
\"python-version\": \"3.5\", \
Expand Down
51 changes: 47 additions & 4 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,7 @@ package_version := $(shell $(PYTHON_CMD) setup.py --version)

# Python versions
python_version := $(shell $(PYTHON_CMD) -c "import sys; sys.stdout.write('{v[0]}.{v[1]}.{v[2]}'.format(v=sys.version_info))")
python_mn_version := $(shell $(PYTHON_CMD) -c "import sys; sys.stdout.write('{v[0]}.{v[1]}'.format(v=sys.version_info))")
pymn := $(shell $(PYTHON_CMD) -c "import sys; sys.stdout.write('py{v[0]}{v[1]}'.format(v=sys.version_info))")
python_m_version := $(shell $(PYTHON_CMD) -c "import sys; sys.stdout.write('{v[0]}'.format(v=sys.version_info))")
python_mn_version := $(shell $(PYTHON_CMD) -c "import sys; sys.stdout.write('{v[0]}.{v[1]}'.format(v=sys.version_info))")
Expand Down Expand Up @@ -181,7 +182,15 @@ check_py_files := \
$(test_end2end_py_files) \

# Packages whose dependencies are checked using pip-missing-reqs
check_reqs_packages := pip_check_reqs virtualenv tox pipdeptree build pytest coverage coveralls flake8 pylint sphinx twine
ifeq ($(python_mn_version),3.6)
check_reqs_packages := pip_check_reqs virtualenv tox pipdeptree build pytest coverage coveralls flake8 pylint twine
else
ifeq ($(python_mn_version),3.7)
check_reqs_packages := pip_check_reqs virtualenv tox pipdeptree build pytest coverage coveralls flake8 pylint twine
else
check_reqs_packages := pip_check_reqs virtualenv tox pipdeptree build pytest coverage coveralls flake8 pylint twine sphinx
endif
endif

ifdef TESTCASES
pytest_opts := $(TESTOPTS) -k "$(TESTCASES)"
Expand Down Expand Up @@ -307,45 +316,79 @@ builddoc: html
html: $(doc_build_dir)/html/docs/index.html
@echo "Makefile: $@ done."

$(doc_build_dir)/html/docs/index.html: Makefile $(doc_dependent_files)
# 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_dir)/html/docs/index.html: Makefile develop_$(pymn)_$(PACKAGE_LEVEL).done $(doc_dependent_files)
ifeq ($(run_sphinx),true)
@echo "Running Sphinx to create HTML pages"
-$(call RM_FUNC,$@)
$(doc_cmd) -b html $(doc_opts) $(doc_build_dir)/html
@echo "Done: Created the HTML pages with top level file: $@"
else
@echo "Skipping Sphinx to create HTML pages on Python version $(python_version)"
endif

.PHONY: pdf
pdf: Makefile $(doc_dependent_files)
pdf: Makefile develop_$(pymn)_$(PACKAGE_LEVEL).done $(doc_dependent_files)
ifeq ($(run_sphinx),true)
@echo "Running Sphinx to create PDF files"
-$(call RM_FUNC,$@)
$(doc_cmd) -b latex $(doc_opts) $(doc_build_dir)/pdf
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(doc_build_dir)/pdf all-pdf
@echo "Done: Created the PDF files in: $(doc_build_dir)/pdf/"
else
@echo "Skipping Sphinx to create PDF files on Python version $(python_version)"
endif
@echo "Makefile: $@ done."

.PHONY: man
man: Makefile $(doc_dependent_files)
man: Makefile develop_$(pymn)_$(PACKAGE_LEVEL).done $(doc_dependent_files)
ifeq ($(run_sphinx),true)
@echo "Running Sphinx to create manual pages"
-$(call RM_FUNC,$@)
$(doc_cmd) -b man $(doc_opts) $(doc_build_dir)/man
@echo "Done: Created the manual pages in: $(doc_build_dir)/man/"
else
@echo "Skipping Sphinx to create manual pages on Python version $(python_version)"
endif
@echo "Makefile: $@ done."

.PHONY: docchanges
docchanges:
ifeq ($(run_sphinx),true)
@echo "Running Sphinx to create doc changes overview file"
$(doc_cmd) -b changes $(doc_opts) $(doc_build_dir)/changes
@echo
@echo "Done: Created the doc changes overview file in: $(doc_build_dir)/changes/"
else
@echo "Skipping Sphinx to create doc changes overview file on Python version $(python_version)"
endif
@echo "Makefile: $@ done."

.PHONY: doclinkcheck
doclinkcheck:
ifeq ($(run_sphinx),true)
@echo "Running Sphinx to check doc links"
$(doc_cmd) -b linkcheck $(doc_opts) $(doc_build_dir)/linkcheck
@echo
@echo "Done: Look for any errors in the above output or in: $(doc_build_dir)/linkcheck/output.txt"
else
@echo "Skipping Sphinx to check doc links on Python version $(python_version)"
endif
@echo "Makefile: $@ done."

.PHONY: doccoverage
doccoverage:
ifeq ($(run_sphinx),true)
@echo "Running Sphinx to create doc coverage results"
$(doc_cmd) -b coverage $(doc_opts) $(doc_build_dir)/coverage
@echo "Done: Created the doc coverage results in: $(doc_build_dir)/coverage/python.txt"
else
@echo "Skipping Sphinx to create doc coverage results on Python version $(python_version)"
endif
@echo "Makefile: $@ done."

.PHONY: check
Expand Down
57 changes: 24 additions & 33 deletions dev-requirements.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,8 +41,8 @@ pytest>=4.6.11,<5.0.0; python_version == '2.7'
pytest>=4.6.11; python_version >= '3.5' and python_version <= '3.9'
pytest>=6.2.5; python_version >= '3.10'
# flake8 up to 6.0.0 has not yet adjusted to the removed interfaces of importlib-metadata 5.0
importlib-metadata>=0.22,<4.3; python_version <= '3.6'
importlib-metadata>=1.1.0,<4.3; python_version >= '3.7'
importlib-metadata>=2.1.3,<5; python_version == '3.6'
importlib-metadata>=4.8.3,<5; python_version >= '3.7'

# packaging is used by pytest, pip-check-reqs, sphinx
# packaging>=20.5 is needed by pip-check-reqs 2.4.3 but it requires only packaging>=16.0
Expand All @@ -65,37 +65,28 @@ coveralls>=3.3.0; python_version >= '3.5'
# PyYAML: covered in direct deps for development

# Sphinx (no imports, invoked via sphinx-build script):
# Sphinx 2.0.0 removed support for Python 2.7
# 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.0.4 fixes safety issues 45775,38330
# Sphinx <4.2.0 fails on Python 3.10 because it tries to import non-existing
# types.Union. This also drives docutils>=0.14.
# Sphinx pins docutils to <0.18 (some versions even to <0.17) but the package
# version resolver in the pip version used on py27 ignores package dependencies
Sphinx>=1.7.6,<2.0.0; python_version == '2.7'
Sphinx>=3.5.4,!=4.0.0,<4.3.0; python_version >= '3.5' and python_version <= '3.9'
Sphinx>=4.2.0; python_version >= '3.10'
docutils>=0.13.1,<0.17; python_version == '2.7'
docutils>=0.13.1,<0.17; python_version >= '3.5' and 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 version 3.0.0 and newer does not support Python 2.7
# GitPython version 3.1.24 requires Python >=3.7
# GitPython version 3.1.27 fixes safety issue #52518
# GitPython 3.1.30 fixes safety issues 52322,52518
GitPython>=2.1.1,<3.0.0; python_version == '2.7'
GitPython>=2.1.1; python_version >= '3.5' and python_version <= '3.6'
GitPython>=3.1.37; python_version >= '3.7'
# Pygments 2.7.4 fixes safety issues 50885,50886
Pygments>=2.4.1; python_version == '2.7'
Pygments>=2.7.4; python_version >= '3.5' and 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 fixes safety issue 42203
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'

# PyLint (no imports, invoked via pylint script)
# Pylint is not run on py27 anymore
Expand Down
9 changes: 9 additions & 0 deletions docs/changes.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,17 @@ Released: not yet

* Increased minimum version of 'prompt-toolkit' package to 3.0.13.

* 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 #547)

**Enhancements:**

* Test: Added Python 3.8 with latest package levels to normal tests because
that is now the minimum version to run Sphinx. (related to issue #547)

**Cleanup:**

**Known issues:**
Expand Down
49 changes: 22 additions & 27 deletions minimum-constraints.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -185,8 +185,8 @@ ruamel.yaml==0.17.21; python_version >= '3.6'
# pytest 4.3.1 solves an issue on Python 3 with minimum package levels
pytest==4.6.11; python_version <= '3.6' and python_version <= '3.9'
pytest==6.2.5; python_version >= '3.10'
importlib-metadata==0.22; python_version <= '3.6'
importlib-metadata==1.1.0; python_version >= '3.7'
importlib-metadata==2.1.3; python_version == '3.6'
importlib-metadata==4.8.3; python_version >= '3.7'

packaging==20.5; python_version <= '3.5'
packaging==21.0; python_version >= '3.6'
Expand All @@ -198,22 +198,24 @@ pytest-cov==2.12.1
coveralls==3.3.0; python_version >= '3.5'

# Sphinx (no imports, invoked via sphinx-build script):
Sphinx==1.7.6; python_version == '2.7'
Sphinx==3.5.4; python_version >= '3.5' and python_version <= '3.9'
Sphinx==4.2.0; python_version >= '3.10'
docutils==0.13.1; python_version == '2.7'
docutils==0.13.1; python_version >= '3.5' and 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.4.1; python_version == '2.7'
Pygments==2.7.4; python_version >= '3.5' and 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'

# PyLint (no imports, invoked via pylint script):
pylint==2.5.2; python_version == '3.5'
Expand Down Expand Up @@ -284,7 +286,7 @@ futures==3.3.0; python_version == "2.7"
gitdb2==2.0.0; python_version <= '3.6'
gitdb==4.0.1; python_version == '3.5'
gitdb==4.0.8; python_version >= '3.6'
imagesize==0.7.1
imagesize==1.3.0
importlib-resources==1.4.0
iniconfig==2.0.0; python_version >= "3.6" # used by pytest since its 6.0.0 which requires py36
Jinja2==2.11.3; python_version <= '3.5'
Expand Down Expand Up @@ -312,14 +314,7 @@ scandir==1.9.0; python_version == '2.7'
singledispatch==3.4.0.3; python_version == "2.7"
smmap2==2.0.1; python_version == '2.7' # requires smmap>=3.0.1
smmap==3.0.1
snowballstemmer==1.2.1
sphinxcontrib-applehelp==1.0.0; python_version >= '3.5'
sphinxcontrib-devhelp==1.0.0; python_version >= '3.5'
sphinxcontrib-htmlhelp==1.0.0; python_version >= '3.5' and python_version <= '3.9'
sphinxcontrib-htmlhelp==2.0.0; python_version >= '3.10'
sphinxcontrib-jsmath==1.0.0; python_version >= '3.5'
sphinxcontrib-qthelp==1.0.0; python_version >= '3.5'
sphinxcontrib-serializinghtml==1.1.5; python_version >= '3.5'
snowballstemmer==2.0.0
toml==0.10.0 # used by pylint and pytest since some version
# tomli 2.0.0 removed support for py36
tomli==1.1.0; python_version == '3.6'
Expand Down

0 comments on commit 3863763

Please sign in to comment.