Fix publish-docs

[forsyth2]

Fix publish-docs in the workflow. ImportError: cannot import name 'environmentfilter' from 'jinja2' (/opt/hostedtoolcache/Python/3.7.12/x64/lib/python3.7/site-packages/jinja2/__init__.py) appears in https://github.com/E3SM-Project/zstash/runs/5795869500?check_suite_focus=true. This issue was introduced with the merging of #205.

[forsyth2]

@tomvothecoder I don't know why this didn't happen with E3SM-Project/e3sm_diags#576 and https://github.com/E3SM-Project/e3sm_diags/actions. Because in #205 zstash was upgraded from an older version than E3SM Diags was at?

[tomvothecoder]

I think you are right. zstash was using black=20.8b1 in pre-commit, so it probably didn't contain the same bug as black=22.1.0.

For this specific issue, jinja2 needs to be pinned < 3.1.
Related issues

• [error occurred in build.] ImportError: cannot import name 'environmentfilter' from 'jinja2'  readthedocs/readthedocs.org#9038
• Jinja 2 imports have been deprecated sphinx-doc/sphinx#10291 (comment)

Pin locations:

• zstash/.github/workflows/build_workflow.yml

  Line 84 in 3c75ea5

  pip install sphinx==3.5.1 sphinx_rtd_theme==0.5.1 sphinx-multiversion==0.2.4 docutils==0.16

• zstash/.github/workflows/release_workflow.yml

  Line 40 in 3c75ea5

  pip install sphinx==3.5.1 sphinx_rtd_theme==0.5.1 sphinx-multiversion==0.2.4 docutils==0.16

• zstash/conda/dev.yml

  Lines 21 to 25 in 3c75ea5

  	# Documentation
  	# =================
  	# If versions are updated, also update in `.github/workflows/workflow.yml`
  	- sphinx=3.5.1
  	- sphinx_rtd_theme=0.5.1

  • Add jinja2 to dev.yml dependencies

[forsyth2]

@tomvothecoder Looks like the fixes in #207 didn't work: https://github.com/E3SM-Project/zstash/runs/5821359209?check_suite_focus=true fails with:

Run pip install sphinx==3.5.1 sphinx_rtd_theme==0.5.1 sphinx-multiversion==0.2.4 docutils==0.16 jinja2<3.1
  pip install sphinx==3.5.1 sphinx_rtd_theme==0.5.1 sphinx-multiversion==0.2.4 docutils==0.16 jinja2<3.1
  shell: /usr/bin/bash -l {0}
  env:
    pythonLocation: /opt/hostedtoolcache/Python/3.7.12/x64
    LD_LIBRARY_PATH: /opt/hostedtoolcache/Python/3.7.12/x64/lib
/home/runner/work/_temp/757fff76-faa8-4d7a-9725-b4631e956582.sh: line 1: 3.1: No such file or directory
Error: Process completed with exit code 1.

[tomvothecoder]

@forsyth2 To denote version ranges with pip, you have to put the package in quotations.

https://stackoverflow.com/questions/8795617/how-to-pip-install-a-package-with-min-and-max-version-range

In this case, it would be pip install sphinx==3.5.1 sphinx_rtd_theme==0.5.1 sphinx-multiversion==0.2.4 docutils==0.16 "jinja2<3.1".

[forsyth2]

@tomvothecoder Thanks, that fixed it!