geo_e4cv nbsphinx error: module 'jinja2.utils' has no attribute 'escape'

[prjemian]

Since switching to [nbsphinx](), the workflow that publishes documentation has failed (https://github.com/bluesky/hklpy/runs/6995106866?check_suite_focus=true, https://github.com/bluesky/hklpy/runs/6995279669?check_suite_focus=true) with this error:

Notebook error:
AttributeError in examples/notebooks/geo_e4cv.ipynb:
module 'jinja2.utils' has no attribute 'escape'
make[1]: *** [Makefile:60: html] Error 2
make[1]: Leaving directory '/home/runner/work/hklpy/hklpy/docs'
make: *** [Makefile:14: html] Error 2
Error: Process completed with exit code 2.

This error might not be limited to this one notebook. The workflow stops on the first error:

make -C docs html
make[1]: Entering directory '/home/runner/work/hklpy/hklpy/docs'
sphinx-build -b html -d build/doctrees   source build/html
Running Sphinx v4.4.0
making output directory... done
[autosummary] generating autosummary for: api.rst, calc.rst, context.rst, diffract.rst, engine.rst, examples/index.rst, examples/notebooks/geo_e4cv.ipynb, examples/notebooks/geo_e6c.ipynb, examples/notebooks/geo_k4cv.ipynb, examples/notebooks/how_additional_parameters.ipynb, ..., geometries.rst, geometry_tables.rst, index.rst, install.rst, overview.rst, ready_to_use.rst, release_notes.rst, sample.rst, user.rst, util.rst
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 28 source files that are out of date
updating environment: [new config] 28 added, 0 changed, 0 removed
reading sources... [  3%] api
reading sources... [  7%] calc
reading sources... [ 10%] context
reading sources... [ 14%] diffract
reading sources... [ 17%] engine
reading sources... [ 21%] examples/index
reading sources... [ 25%] examples/notebooks/geo_e4cv
Notebook error:
AttributeError in examples/notebooks/geo_e4cv.ipynb:
module 'jinja2.utils' has no attribute 'escape'
make[1]: *** [Makefile:60: html] Error 2
make[1]: Leaving directory '/home/runner/work/hklpy/hklpy/docs'
make: *** [Makefile:14: html] Error 2
Error: Process completed with exit code 2.

[prjemian]

Is this due to Python version (3.8 is used)? Try Py3.9.

[prjemian]

Aha! Swap the order of the channels here. https://github.com/bluesky/hklpy/blob/de21ead8c784ea4257a209c0cc9cd47864bc3637/.github/workflows/publish-docs.yml#L59

[prjemian]

Trying to replicate, so far cannot reproduce locally:

micromamba create -y -n dev-hklpy python=3.8
micromamba install -y -n dev-hklpy -f environment.yml
micromamba install -y -n dev-hklpy jupyter nbconvert "sphinx=4.4.0" sphinx_rtd_theme nbsphinx sphinxcontrib-napoleon make flake8 black pandoc -c conda-forge -c defaults

eval "$(micromamba shell hook --shell=bash)"
micromamba activate dev-hklpy
pip install -e .
make -C docs clean html

[prjemian]

Locally, no problem building with either Py 3.8 or 3.9. Need to get a list of the specific packages installed in the Actions workflow run.

Note Sphinx version 5.0.2 is available but the workflow installs 4.4.0. Curious, that.

[prjemian]

Good time to switch the workflow to micromamba (#231).

[prjemian]

I'm not convinced that module 'jinja2.utils' has no attribute 'escape' is the real problem here.

[prjemian]

See: https://github.com/jupyter/nbconvert/issues/1736 which means to compare the jinja2 version between workflow and local.

[prjemian]

It's a miracle, with commit 11fa1ad (for #231), the documentation builds without error.