bug: cannot generate docs on python 3.10

[sierzput]

output from make docs:

make -C docs html
make[1]: Entering directory '/mnt/c/Repos/python-docx/docs'
sphinx-build -b html -d .build/doctrees   . .build/html
Traceback (most recent call last):
  File "/mnt/c/Repos/python-docx/.venv/bin/sphinx-build", line 5, in <module>
    from sphinx.cmd.build import main
  File "/mnt/c/Repos/python-docx/.venv/lib/python3.10/site-packages/sphinx/cmd/build.py", line 25, in <module>
    from sphinx.application import Sphinx
  File "/mnt/c/Repos/python-docx/.venv/lib/python3.10/site-packages/sphinx/application.py", line 48, in <module>
    from sphinx.util.tags import Tags
  File "/mnt/c/Repos/python-docx/.venv/lib/python3.10/site-packages/sphinx/util/tags.py", line 11, in <module>
    from jinja2 import nodes
  File "/mnt/c/Repos/python-docx/.venv/lib/python3.10/site-packages/jinja2/__init__.py", line 6, in <module>
    from markupsafe import escape
  File "/mnt/c/Repos/python-docx/.venv/lib/python3.10/site-packages/markupsafe/__init__.py", line 13, in <module>
    from collections import Mapping
ImportError: cannot import name 'Mapping' from 'collections' (/usr/lib/python3.10/collections/__init__.py)
make[1]: *** [Makefile:20: html] Error 1
make[1]: Leaving directory '/mnt/c/Repos/python-docx/docs'
make: *** [Makefile:43: docs] Error 2

[scanny]

Did you run pip install -r requirements-docs.txt in your virtualenv? The versions of Sphinx and its dependencies are quite specific for these docs. It works for me locally and on ReadTheDocs so I'd look there first.

[sierzput]

Yes, I installed requirements-docs.txt in my virtualenv. Problem is fixed when I updated dependencies from requirements-docs.txt to the latest versions. It looks like an issue with some dependency, probably on Python 3.10. Which Python version do you use @scanny ?

[scanny]

My local virtualenv for python-docx has Python 3.8.18 installed. I expect that was on purpose because I got a new machine a few months ago, and I vaguely remember downgrading it for the purpose of building the docs.

[sierzput]

I think it would be good to update soon anyway, because the end of support for Python 3.8 is October 2024.

[scanny]

Yeah, at some point ReadTheDocs won't support that version anymore and we'll be forced to update I suppose. Switching to the new templates will require pretty broad changes I expect so that's not going to be a quick job :)

The docs aren't really something designed for folks to build for themselves. I don't even use them locally myself, I always go to ReadTheDocs to consult them. But I suppose if you were working offline for some reason that might be handy.