This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Pin Jinja2 to fix docs build
Type: Stage: patch review
Components: Documentation Versions: Python 3.10, Python 3.9, Python 3.8, Python 3.7
process
Status: open Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Maciej Olko, docs@python, hugovk, lukasz.langa, miss-islington, ned.deily, steve.dower
Priority: normal Keywords: patch

Created on 2022-03-28 08:17 by hugovk, last changed 2022-04-11 14:59 by admin.

Pull Requests
URL Status Linked Edit
PR 32111 merged Maciej Olko, 2022-03-28 11:12
PR 32109 merged Maciej Olko, 2022-03-28 11:17
PR 32153 merged hugovk, 2022-03-28 14:23
PR 32154 merged hugovk, 2022-03-28 14:24
PR 32161 merged steve.dower, 2022-03-28 20:21
PR 32163 merged steve.dower, 2022-03-28 20:58
PR 32167 closed miss-islington, 2022-03-28 23:46
PR 32168 closed miss-islington, 2022-03-28 23:46
PR 32169 merged miss-islington, 2022-03-28 23:46
PR 32182 merged steve.dower, 2022-03-29 19:01
PR 32183 open steve.dower, 2022-03-29 21:08
Messages (14)
msg416149 - (view) Author: Hugo van Kemenade (hugovk) * (Python triager) Date: 2022-03-28 08:17
The docs build on GitHub Actions is passing on `main` but has started failing for the `3.7` - `3.10` branches:

```
Missing the required blurb or sphinx-build tools.
Please run 'make venv' to install local copies.

make[1]: *** [Makefile:50: build] Error 1
```

https://github.com/python/cpython/actions/workflows/doc.yml
https://github.com/python/cpython/runs/5714593700?check_suite_focus=true

This is because the `PATH=./venv/bin:$PATH sphinx-build --version` check is failing:

```
/home/runner/work/cpython/cpython/Doc/venv/lib/python3.10/site-packages/sphinx/util/docutils.py:45: DeprecationWarning: distutils Version classes are deprecated. Use packaging.version instead.
  __version_info__ = tuple(LooseVersion(docutils.__version__).version)
Traceback (most recent call last):
  File "/home/runner/work/cpython/cpython/Doc/./venv/bin/sphinx-build", line 5, in <module>
    from sphinx.cmd.build import main
  File "/home/runner/work/cpython/cpython/Doc/venv/lib/python3.10/site-packages/sphinx/cmd/build.py", line 25, in <module>
    from sphinx.application import Sphinx
  File "/home/runner/work/cpython/cpython/Doc/venv/lib/python3.10/site-packages/sphinx/application.py", line 42, in <module>
    from sphinx.registry import SphinxComponentRegistry
  File "/home/runner/work/cpython/cpython/Doc/venv/lib/python3.10/site-packages/sphinx/registry.py", line 24, in <module>
    from sphinx.builders import Builder
  File "/home/runner/work/cpython/cpython/Doc/venv/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 26, in <module>
    from sphinx.util import import_object, logging, rst, progress_message, status_iterator
  File "/home/runner/work/cpython/cpython/Doc/venv/lib/python3.10/site-packages/sphinx/util/rst.py", line 22, in <module>
    from jinja2 import environmentfilter
ImportError: cannot import name 'environmentfilter' from 'jinja2' (/home/runner/work/cpython/cpython/Doc/venv/lib/python3.10/site-packages/jinja2/__init__.py)
```

This is because `3.10` and `3.9` are still using old versions of Sphinx (3.2.1 and 2.4.4 respectively) which is incompatible with the newest Jinja2:

https://github.com/pallets/jinja/issues/1630

`main` is using a newer Sphinx (4.2.0), so it passes.

Bumping to Sphinx 4.5.0 will fix both `3.9` and `3.10`. `3.7` and `3.8` are affected too. We can bump `main` to use `4.5.0` as well.
msg416151 - (view) Author: Hugo van Kemenade (hugovk) * (Python triager) Date: 2022-03-28 08:32
re: https://bugs.python.org/issue45618#msg416017

Maciej Olko, please could you update these PRs to keep the Sphinx version the same and only pin Jinja2 to match?

3.7: https://github.com/python/cpython/pull/32109
3.8: https://github.com/python/cpython/pull/32111

I guess update them to use this bpo too. Thanks!
msg416158 - (view) Author: Maciej Olko (Maciej Olko) * Date: 2022-03-28 11:24
I've update both PRs to contain the pin only.
msg416167 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2022-03-28 13:47
Thank you both for addressing this. The main reason for minimizing changes to the docs build chain for brances in bugfix or security-fix-only phases is that many distributors of Python also release the Python docs as a package and they do not necessarily rely on using our fairly-recent venv step in the Docs Makefile. In particular, they want to use the versions of Sphinx et al that they release as packages. If we change the required versions for these mid-stream, they not only have to update the docs themselves but have to go through the process of updating the other packages (like Sphinx) which may have other consequences. This can also impact our own on-line doc building process. (Version updates for a new Python feature release prior to its entering beta phase are not a problem.) So it is best to do the minimal amount of version updating for releases in the field, preferably none (as in pinning existing versions). In that spirit, we should also just pin the Jinja2 version for 3.10 and 3.9.
msg416171 - (view) Author: Hugo van Kemenade (hugovk) * (Python triager) Date: 2022-03-28 14:28
I cherry picked Maciej's 3.8 commit into 3.9 and 3.10 PRs:

3.9: https://github.com/python/cpython/pull/32153
3.10: https://github.com/python/cpython/pull/32154

And marking this issue as not relevant to 3.11; instead I bumped the Sphinx version in bpo-47126 / gh-32124 as it's directly relevant there.

Thanks!
msg416194 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2022-03-28 17:05
New changeset 25f00bfb264a3197ac91c41cdec15036fd8401f1 by m-aciek in branch '3.7':
bpo-47138: Fix documentation build by pinning Jinja version to 3.0.3 (GH-32111)
https://github.com/python/cpython/commit/25f00bfb264a3197ac91c41cdec15036fd8401f1
msg416195 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2022-03-28 17:06
New changeset 9194a7b8990a0feec1209b1e5694df3bf42906d8 by Hugo van Kemenade in branch '3.10':
bpo-47138: Fix documentation build by pinning Jinja version to 3.0.3 (GH-32154)
https://github.com/python/cpython/commit/9194a7b8990a0feec1209b1e5694df3bf42906d8
msg416196 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2022-03-28 17:19
New changeset 25c40bd994aa0da75283c5efdd71ba26c734b67e by Hugo van Kemenade in branch '3.9':
bpo-47138: Fix documentation build by pinning Jinja version to 3.0.3 (GH-32153)
https://github.com/python/cpython/commit/25c40bd994aa0da75283c5efdd71ba26c734b67e
msg416197 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2022-03-28 17:25
Thanks, everyone! Merged for 3.10.5, 3.9.13, and 3.7.14. I'll leave the issue in pending state until merged for 3.8.14.
msg416209 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2022-03-28 20:38
New changeset 295114dcd32b3aad5453e5e15e9e1befa0e5ca01 by Steve Dower in branch 'main':
bpo-47138: Ensure Windows docs build uses the same pinned version as other platforms (GH-32161)
https://github.com/python/cpython/commit/295114dcd32b3aad5453e5e15e9e1befa0e5ca01
msg416233 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2022-03-28 23:46
New changeset 0dfabf9b4a58b835b61fc3d17784d4746f677e56 by Steve Dower in branch '3.10':
bpo-47138: Ensure Windows docs build uses the same pinned version as other platforms (GH-32161)
https://github.com/python/cpython/commit/0dfabf9b4a58b835b61fc3d17784d4746f677e56
msg416235 - (view) Author: miss-islington (miss-islington) Date: 2022-03-29 00:10
New changeset d2c6a4428d52c108f4b06dcd1bb86023541c60ce by Miss Islington (bot) in branch '3.9':
bpo-47138: Ensure Windows docs build uses the same pinned version as other platforms (GH-32161)
https://github.com/python/cpython/commit/d2c6a4428d52c108f4b06dcd1bb86023541c60ce
msg416285 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2022-03-29 19:11
New changeset d97497bf1cc6abd4a9a67d8da4f00cf13b3af4b3 by Steve Dower in branch '3.7':
bpo-47138: Ensure Windows docs build uses the same pinned version as other platforms (GH-32182)
https://github.com/python/cpython/commit/d97497bf1cc6abd4a9a67d8da4f00cf13b3af4b3
msg416983 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2022-04-08 13:06
New changeset d35af52caae844cb4ea0aff06fa3fc5328708af1 by m-aciek in branch '3.8':
[3.8] bpo-47138: Fix documentation build by pinning Jinja version to 3.0.3 (GH-32109)
https://github.com/python/cpython/commit/d35af52caae844cb4ea0aff06fa3fc5328708af1
History
Date User Action Args
2022-04-11 14:59:57adminsetgithub: 91294
2022-04-08 13:06:24lukasz.langasetnosy: + lukasz.langa
messages: + msg416983
2022-03-29 21:08:11steve.dowersetpull_requests: + pull_request30260
2022-03-29 19:11:06ned.deilysetmessages: + msg416285
2022-03-29 19:01:51steve.dowersetpull_requests: + pull_request30259
2022-03-29 00:10:54miss-islingtonsetmessages: + msg416235
2022-03-28 23:46:56miss-islingtonsetpull_requests: + pull_request30247
2022-03-28 23:46:51miss-islingtonsetpull_requests: + pull_request30246
2022-03-28 23:46:46miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request30245
2022-03-28 23:46:25steve.dowersetmessages: + msg416233
2022-03-28 20:58:52steve.dowersetstage: resolved -> patch review
pull_requests: + pull_request30241
2022-03-28 20:38:48steve.dowersetmessages: + msg416209
2022-03-28 20:21:05steve.dowersetstatus: pending -> open
nosy: + steve.dower

pull_requests: + pull_request30239
2022-03-28 17:25:55ned.deilysetstatus: open -> pending
resolution: fixed
messages: + msg416197

stage: patch review -> resolved
2022-03-28 17:19:59ned.deilysetmessages: + msg416196
2022-03-28 17:06:25ned.deilysetmessages: + msg416195
2022-03-28 17:05:10ned.deilysetmessages: + msg416194
2022-03-28 14:28:12hugovksettitle: Bump Sphinx or pin Jinja2 to fix docs build -> Pin Jinja2 to fix docs build
messages: + msg416171
versions: - Python 3.11
2022-03-28 14:24:10hugovksetpull_requests: + pull_request30235
2022-03-28 14:23:53hugovksetpull_requests: + pull_request30234
2022-03-28 13:47:57ned.deilysetnosy: + ned.deily
messages: + msg416167
2022-03-28 11:24:11Maciej Olkosetmessages: + msg416158
2022-03-28 11:17:09Maciej Olkosetpull_requests: + pull_request30232
2022-03-28 11:12:14Maciej Olkosetkeywords: + patch
nosy: + Maciej Olko

pull_requests: + pull_request30231
stage: patch review
2022-03-28 08:32:05hugovksetmessages: + msg416151
title: Bump Sphinx to fix docs build -> Bump Sphinx or pin Jinja2 to fix docs build
2022-03-28 08:17:25hugovkcreate