[BUG] EDS book build error - environment issue

[Bryn Noel Ubald]

Describe the bug

When attempting to build the jupyter-book using either of the provided requirements.txt or environment.yml files, I receive the following error:

❯ jupyter-book build .
Running Jupyter-Book v0.12.3
Source Folder: /data/hpcdata/users/username/git/turing/environmental-ds-book/book
Config Path: /data/hpcdata/users/username/git/turing/environmental-ds-book/book/_config.yml
Output Path: /data/hpcdata/users/username/git/turing/environmental-ds-book/book/_build/html

===============================================================================

Warning: Validation errors in config:
- False is not of type 'string' [key path: 'launch_buttons/binderhub_url']

===============================================================================

Running Sphinx v4.5.0
loading translations [en]... done

Sphinx version error:
The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0; it therefore cannot be built with this version.
Traceback (most recent call last):
  File "/data/hpcdata/users/username/miniconda3/envs/eds-book/lib/python3.9/site-packages/sphinx/registry.py", line 438, in load_extension
    metadata = setup(app)
  File "/data/hpcdata/users/username/miniconda3/envs/eds-book/lib/python3.9/site-packages/sphinxcontrib/applehelp/__init__.py", line 230, in setup
    app.require_sphinx('5.0')
  File "/data/hpcdata/users/username/miniconda3/envs/eds-book/lib/python3.9/site-packages/sphinx/application.py", line 393, in require_sphinx
    raise VersionRequirementError(version)
sphinx.errors.VersionRequirementError: 5.0

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/data/hpcdata/users/username/miniconda3/envs/eds-book/lib/python3.9/site-packages/jupyter_book/sphinx.py", line 114, in build_sphinx
    app = Sphinx(
  File "/data/hpcdata/users/username/miniconda3/envs/eds-book/lib/python3.9/site-packages/sphinx/application.py", line 219, in __init__
    self.setup_extension(extension)
  File "/data/hpcdata/users/username/miniconda3/envs/eds-book/lib/python3.9/site-packages/sphinx/application.py", line 380, in setup_extension
    self.registry.load_extension(self, extname)
  File "/data/hpcdata/users/username/miniconda3/envs/eds-book/lib/python3.9/site-packages/sphinx/registry.py", line 441, in load_extension
    raise VersionRequirementError(
sphinx.errors.VersionRequirementError: The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0; it therefore cannot be built with this version.

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/data/hpcdata/users/username/miniconda3/envs/eds-book/bin/jupyter-book", line 8, in <module>
    sys.exit(main())
  File "/data/hpcdata/users/username/miniconda3/envs/eds-book/lib/python3.9/site-packages/click/core.py", line 1157, in __call__
    return self.main(*args, **kwargs)
  File "/data/hpcdata/users/username/miniconda3/envs/eds-book/lib/python3.9/site-packages/click/core.py", line 1078, in main
    rv = self.invoke(ctx)
  File "/data/hpcdata/users/username/miniconda3/envs/eds-book/lib/python3.9/site-packages/click/core.py", line 1688, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/data/hpcdata/users/username/miniconda3/envs/eds-book/lib/python3.9/site-packages/click/core.py", line 1434, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/data/hpcdata/users/username/miniconda3/envs/eds-book/lib/python3.9/site-packages/click/core.py", line 783, in invoke
    return __callback(*args, **kwargs)
  File "/data/hpcdata/users/username/miniconda3/envs/eds-book/lib/python3.9/site-packages/jupyter_book/cli/main.py", line 323, in build
    builder_specific_actions(
  File "/data/hpcdata/users/username/miniconda3/envs/eds-book/lib/python3.9/site-packages/jupyter_book/cli/main.py", line 535, in builder_specific_actions
    raise RuntimeError(_message_box(msg, color="red", doprint=False)) from result
RuntimeError: 
===============================================================================

There was an error in building your book. Look above for the cause.

===============================================================================

How To Reproduce

The above error is produced when building the EDS book either via book/requirements.txt or book/environment.yml following CONTRIBUTING.md

This would probably affect the conda based netlify deployment as well upon next commit to the main branch (If I'm not the only one getting this error 😅)?

Install via pip

1. pip install -r book/requirements.txt
2. cd book/
3. jupyter-book build .

Install via conda

(Following the netlify.toml setup)

1. conda env create -f book/environment.yml
2. cd book/
3. jupyter-book build .

Expected behaviour

The build to complete successfully and the generation of the html outputs under book/_build/html

Environment (generate for Linux, macOS and 64-bit Windows)

conda-lock.txt

Additional information

This issue has been brought up in the Sphinx repo in sphinx-doc/sphinx#11890 last month.

Issue is caused by pinned version of jupyter-book requiring Sphinx<5.

Unpinned dependencies in Sphinx were updated and not backwards compatibile with older version (Sphinx<5).

Fix would be to either update pinned Jupyter book version, or pin the Sphinx dependencies themselves.

[Alejandro ©]

Thanks for flagging this! Both fixes sound good to me. I'm more inclined for setting the latest stable version of Jupyter Book (v.1.0.0) which includes some major upgrades and support to myst-related development (see here).