saltstack / saltstack/salt

[BUG] Documentation fails to build due to too new Jinja version

Open
#63,703 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug needs-triage
Dominant language
Python
Stars
15.7k
Forks
5.6k
Avg merge
2d 44m
Merged PRs (30d)
80

Description

Description
The documentation in this repo fails to build when following these instructions.

Steps to Reproduce the behavior

rm -rf ~/.pyenv
git clone https://github.com/pyenv/pyenv.git ~/.pyenv
export PATH="$HOME/.pyenv/bin:$PATH"
git clone https://github.com/pyenv/pyenv-virtualenv.git $(pyenv root)/plugins/pyenv-virtualenv

# this would be in ~/.bashrc
export PATH="$HOME/.pyenv/bin:$PATH"
export PYENV_ROOT="$HOME/.pyenv"
command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

pyenv install 3.7.0
CC=clang pyenv install 3.7.0
pyenv virtualenv 3.7.0 salt
pyenv activate salt
git clone --depth=1 --origin salt https://github.com/saltstack/salt.git
cd salt/
git remote add faivirol https://github.com/faivirol/salt.git
git fetch salt/upstream
git pull
pip install --upgrade pip  # package installation failed otherwise
python -m pip install pre-commit nox
pre-commit install

pyenv install 3.7.15
pyenv virtualenv 3.7.15 salt-docs
echo 'salt-docs' > .python-version
pyenv exec pip install -U pip setuptools wheel
pyenv exec pip install nox
python -m nox -e 'docs-html(compress=False, clean=False)'; cd doc/_build/html; python -m webbrowser http://localhost:8000/contents.html; python -m http.server

This gives this traceback:

Traceback (most recent call last):
  File "/home/user/salt/.nox/docs-html-compress-false-clean-false/bin/sphinx-build", line 5, in <module>
    from sphinx.cmd.build import main
  File "/home/user/salt/.nox/docs-html-compress-false-clean-false/lib/python3.7/site-packages/sphinx/cmd/build.py", line 25, in <module>
    from sphinx.application import Sphinx
  File "/home/user/salt/.nox/docs-html-compress-false-clean-false/lib/python3.7/site-packages/sphinx/application.py", line 43, in <module>
    from sphinx.registry import SphinxComponentRegistry
  File "/home/user/salt/.nox/docs-html-compress-false-clean-false/lib/python3.7/site-packages/sphinx/registry.py", line 24, in <module>
    from sphinx.builders import Builder
  File "/home/user/salt/.nox/docs-html-compress-false-clean-false/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 26, in <module>
    from sphinx.util import import_object, logging, progress_message, rst, status_iterator
  File "/home/user/salt/.nox/docs-html-compress-false-clean-false/lib/python3.7/site-packages/sphinx/util/rst.py", line 21, in <module>
    from jinja2 import Environment, environmentfilter
ImportError: cannot import name 'environmentfilter' from 'jinja2' (/home/user/salt/.nox/docs-html-compress-false-clean-false/lib/python3.7/site-packages/jinja2/__init__.py)

Additional context
Pinning jinja2 in requirements/static/ci/py3.7/docs.txt to 3.0.3 instead of 3.1.2 as suggested here and here fixes the issue for me, although I don't know if that breaks something else.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with requirements/static/ci/py3.7/docs.txt and compare its Jinja version with the environmentfilter import shown in the traceback. Run the documented setup and python -m nox -e 'docs-html(compress=False, clean=False)' to verify the failure. Done means the documentation build completes without this ImportError.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
build-system, documentation
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.