Possibly failing docs builds

[GenevieveBuckley]

Describe the bug
Building the jupyter book docs for magicgui currently produces an error. I found a workaround (described below), but wanted to mention it here in case you notice something similar happen in the docs CI at some point.

Since magicgui builds and releases documentation infrequently (eg: on new releases), so it's possible that this problem will get fixed before it actually impacts anything for the CI here.

Workarounds

There is a workaround that avoids this, suggested changing execute_notebooks to force (from cache). This worked for me, and I could build the jupyter-book locally.

It's odd that this made a difference, since I was attempting to build the docs in a totally new environment with a new clone of the repo, so there should not have been anything cached in the first place? But now I can build the docs, so I'm not complaining.

jupyter-book/jupyter-book#1902 (comment)

Update: after changing cache to force in the following block, this 'ExtensionError' can be skipped.

 execute:
   execute_notebooks: force

A different workaround, pinning the version of jupyter-server: ProjectPythia/cookbook-template#100 (comment)

To Reproduce
Steps to reproduce the behavior:

1. Setup magicgui-dev environment according to the contributing guide.
2. Install the docs dependencies, following .github/workflows/deploy_docs.yml (so pretty much just also do pip install docs/requirements.txt into your dev environment)
3. Run jupyter-book build docs
4. Observe the error:

Details:

(magicgui-dev) genevieb@192-168-1-102 magicgui % jupyter-book build docs
Running Jupyter-Book v0.13.0
Source Folder: /Users/genevieb/Documents/GitHub/magicgui/docs
Config Path: /Users/genevieb/Documents/GitHub/magicgui/docs/_config.yml
Output Path: /Users/genevieb/Documents/GitHub/magicgui/docs/_build/html
Running Sphinx v4.5.0
loading pickled environment... done
myst v0.15.2: MdParserConfig(renderer='sphinx', commonmark_only=False, enable_extensions=['colon_fence', 'dollarmath', 'linkify', 'substitution', 'tasklist'], dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', disable_syntax=[], url_schemes=['mailto', 'http', 'https'], heading_anchors=None, heading_slug_func=None, html_meta=[], footnote_transition=True, substitutions=[], sub_delimiters=['{', '}'], words_per_minute=200)
[autosummary] generating autosummary for: api/_autosummary/magicgui.type_map.get_widget_class.rst, api/_autosummary/magicgui.type_map.register_type.rst, api/_autosummary/magicgui.widgets.CheckBox.rst, api/_autosummary/magicgui.widgets.ComboBox.rst, api/_autosummary/magicgui.widgets.Container.rst, api/_autosummary/magicgui.widgets.DateEdit.rst, api/_autosummary/magicgui.widgets.DateTimeEdit.rst, api/_autosummary/magicgui.widgets.Dialog.rst, api/_autosummary/magicgui.widgets.EmptyWidget.rst, api/_autosummary/magicgui.widgets.FileEdit.rst, ..., usage/_autosummary/magicgui.widgets.Table.rst, usage/_autosummary/magicgui.widgets.TextEdit.rst, usage/_autosummary/magicgui.widgets.TimeEdit.rst, usage/configuration.md, usage/direct_api.md, usage/installation.md, usage/main_window.md, usage/quickstart.md, usage/types_widgets.md, usage/widget_overview.md
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: executing outdated notebooks... failed

Extension error (myst_nb.execution):
Handler <function update_execution_cache at 0x108f950d0> for event 'env-get-outdated' threw an exception (exception: jsonschema 3.2.0 has no such extra feature 'format-nongpl')
Traceback (most recent call last):
  File "/Users/genevieb/mambaforge/envs/magicgui-dev/lib/python3.9/site-packages/pkg_resources/__init__.py", line 2751, in requires
    deps.extend(dm[safe_extra(ext)])
KeyError: 'format-nongpl'

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

Traceback (most recent call last):
  File "/Users/genevieb/mambaforge/envs/magicgui-dev/lib/python3.9/site-packages/sphinx/events.py", line 94, in emit
    results.append(listener.handler(self.app, *args))
  File "/Users/genevieb/mambaforge/envs/magicgui-dev/lib/python3.9/site-packages/myst_nb/execution.py", line 76, in update_execution_cache
    _stage_and_execute(
  File "/Users/genevieb/mambaforge/envs/magicgui-dev/lib/python3.9/site-packages/myst_nb/execution.py", line 279, in _stage_and_execute
    execute_staged_nb(
  File "/Users/genevieb/mambaforge/envs/magicgui-dev/lib/python3.9/site-packages/myst_nb/execution.py", line 311, in execute_staged_nb
    executor = load_executor("basic", cache_base, logger=LOGGER)
  File "/Users/genevieb/mambaforge/envs/magicgui-dev/lib/python3.9/site-packages/jupyter_cache/executors/base.py", line 78, in load_executor
    execute_cls = entry_points[0].load()
  File "/Users/genevieb/mambaforge/envs/magicgui-dev/lib/python3.9/site-packages/pkg_resources/__init__.py", line 2467, in load
    self.require(*args, **kwargs)
  File "/Users/genevieb/mambaforge/envs/magicgui-dev/lib/python3.9/site-packages/pkg_resources/__init__.py", line 2490, in require
    items = working_set.resolve(reqs, env, installer, extras=self.extras)
  File "/Users/genevieb/mambaforge/envs/magicgui-dev/lib/python3.9/site-packages/pkg_resources/__init__.py", line 820, in resolve
    new_requirements = dist.requires(req.extras)[::-1]
  File "/Users/genevieb/mambaforge/envs/magicgui-dev/lib/python3.9/site-packages/pkg_resources/__init__.py", line 2753, in requires
    raise UnknownExtra(
pkg_resources.UnknownExtra: jsonschema 3.2.0 has no such extra feature 'format-nongpl'

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

Traceback (most recent call last):
  File "/Users/genevieb/mambaforge/envs/magicgui-dev/lib/python3.9/site-packages/jupyter_book/sphinx.py", line 167, in build_sphinx
    app.build(force_all, filenames)
  File "/Users/genevieb/mambaforge/envs/magicgui-dev/lib/python3.9/site-packages/sphinx/application.py", line 330, in build
    self.builder.build_update()
  File "/Users/genevieb/mambaforge/envs/magicgui-dev/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 286, in build_update
    self.build(to_build,
  File "/Users/genevieb/mambaforge/envs/magicgui-dev/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 300, in build
    updated_docnames = set(self.read())
  File "/Users/genevieb/mambaforge/envs/magicgui-dev/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 371, in read
    for docs in self.events.emit('env-get-outdated', self.env, added, changed, removed):
  File "/Users/genevieb/mambaforge/envs/magicgui-dev/lib/python3.9/site-packages/sphinx/events.py", line 102, in emit
    raise ExtensionError(__("Handler %r for event %r threw an exception") %
sphinx.errors.ExtensionError: Handler <function update_execution_cache at 0x108f950d0> for event 'env-get-outdated' threw an exception (exception: jsonschema 3.2.0 has no such extra feature 'format-nongpl')

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

Traceback (most recent call last):
  File "/Users/genevieb/mambaforge/envs/magicgui-dev/bin/jupyter-book", line 8, in <module>
    sys.exit(main())
  File "/Users/genevieb/mambaforge/envs/magicgui-dev/lib/python3.9/site-packages/click/core.py", line 1130, in __call__
    return self.main(*args, **kwargs)
  File "/Users/genevieb/mambaforge/envs/magicgui-dev/lib/python3.9/site-packages/click/core.py", line 1055, in main
    rv = self.invoke(ctx)
  File "/Users/genevieb/mambaforge/envs/magicgui-dev/lib/python3.9/site-packages/click/core.py", line 1657, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/Users/genevieb/mambaforge/envs/magicgui-dev/lib/python3.9/site-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/Users/genevieb/mambaforge/envs/magicgui-dev/lib/python3.9/site-packages/click/core.py", line 760, in invoke
    return __callback(*args, **kwargs)
  File "/Users/genevieb/mambaforge/envs/magicgui-dev/lib/python3.9/site-packages/jupyter_book/cli/main.py", line 323, in build
    builder_specific_actions(
  File "/Users/genevieb/mambaforge/envs/magicgui-dev/lib/python3.9/site-packages/jupyter_book/cli/main.py", line 531, 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.

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

Expected behavior

I expected the HTML for the jupyter book to be generated successfully.

Screenshots
Not applicable.

Environment (please complete the following information):

• OS: [e.g. Windows, Mac] Observed on an M1 Mac & on Ubuntu 20.04
• backend: [e.g. Qt 5.13.0] pyqt5
• magicgui version [e.g. 0.1.0] development version

[tlambert03]

Thanks @GenevieveBuckley I appreciate it. Note that the docs are being completely redone without jupyter book in #527, so good to note these here, but won't be relevant once that's done

[GenevieveBuckley]

Oh, I had not seen that PR switching to mkdocs. Well, in that case we have two reasons this problem might never actually pop up here, and I don't think we need to keep this issue open.