docs: RTD build failing due to jupyter_client.kernelspec.NoSuchKernel

[wang-boyu]

Describe the bug

ReadtheDocs build is failing due to error jupyter_client.kernelspec.NoSuchKernel: No such kernel named mesa_geo

Full Error

Running Sphinx v8.0.2
loading translations [en]... done
making output directory... done
WARNING: html_static_path entry '_static' does not exist
Converting `source_suffix = ['.rst', '.md']` to `source_suffix = {'.rst': 'restructuredtext', '.md': 'restructuredtext'}`.
loading intersphinx inventory 'python' from https://docs.python.org/3/objects.inv ...
myst v4.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=set(), disable_syntax=[], all_links_external=False, links_external_new_tab=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_sort=True, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, 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', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
myst-nb v1.1.1: NbParserConfig(custom_formats={}, metadata_key='mystnb', cell_metadata_key='mystnb', kernel_rgx_aliases={}, eval_name_regex='^[a-zA-Z_][a-zA-Z0-9_]*$', execution_mode='cache', execution_cache_path='', execution_excludepatterns=(), execution_timeout=60, execution_in_temp=False, execution_allow_errors=False, execution_raise_on_error=False, execution_show_tb=False, merge_streams=False, render_plugin='default', remove_code_source=False, remove_code_outputs=False, code_prompt_show='Show code cell {type}', code_prompt_hide='Hide code cell {type}', number_source_lines=False, output_stderr='show', render_text_lexer='myst-ansi', render_error_lexer='ipythontb', render_image_options={}, render_figure_options={}, render_markdown_format='commonmark', output_folder='build', append_css=True, metadata_to_fm=False)
Using jupyter-cache at: /home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/checkouts/main/_readthedocs/.jupyter_cache
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 17 source files that are out of date
updating environment: [new config] 17 added, 0 changed, 0 removed
reading sources... [  6%] README
/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/myst_nb/core/read.py:71: RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
  if path.endswith(suffix):
reading sources... [ 12%] apis/api_main
/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/myst_nb/core/read.py:71: RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
  if path.endswith(suffix):
reading sources... [ 18%] apis/geo_base
reading sources... [ 24%] apis/geoagent
reading sources... [ 29%] apis/geospace
reading sources... [ 35%] apis/raster_layers
reading sources... [ 41%] apis/tile_layers
reading sources... [ 47%] apis/visualization
/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/solara/validate_hooks.py:122: UserWarning: /home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/mesa/experimental/jupyter_viz.py:163: JupyterViz: `use_state` found within a nested function created on line 155
To suppress this check, replace the line with:
        grid_layout, set_grid_layout = solara.use_state(grid_layout_initial)  # noqa: SH104

Make sure you understand the consequences of this, by reading about the rules of hooks at:
    https://solara.dev/documentation/advanced/understanding/rules-of-hooks

  warnings.warn(str(e))
reading sources... [ 53%] examples/geo_schelling
/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/myst_nb/core/read.py:71: RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
  if path.endswith(suffix):
reading sources... [ 59%] examples/geo_schelling_points
/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/myst_nb/core/read.py:71: RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
  if path.endswith(suffix):
reading sources... [ 65%] examples/geo_sir
/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/myst_nb/core/read.py:71: RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
  if path.endswith(suffix):
reading sources... [ 71%] examples/overview
/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/myst_nb/core/read.py:71: RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
  if path.endswith(suffix):
reading sources... [ 76%] examples/population
/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/myst_nb/core/read.py:71: RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
  if path.endswith(suffix):
reading sources... [ 82%] examples/rainfall
/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/myst_nb/core/read.py:71: RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
  if path.endswith(suffix):
reading sources... [ 88%] examples/urban_growth
/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/myst_nb/core/read.py:71: RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
  if path.endswith(suffix):
reading sources... [ 94%] index
/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/myst_nb/core/read.py:71: RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
  if path.endswith(suffix):
reading sources... [100%] tutorials/intro_tutorial
/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/myst_nb/core/read.py:71: RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
  if path.endswith(suffix):
/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/checkouts/main/docs/tutorials/intro_tutorial.ipynb: Executing notebook using local CWD [mystnb]
WARNING: autodoc: failed to import module 'modules.__init__' from module 'visualization'; the following exception was raised:
No module named 'visualization.modules' [autodoc.import_object]
WARNING: autodoc: failed to import module 'modules.MapVisualization' from module 'visualization'; the following exception was raised:
No module named 'visualization.modules' [autodoc.import_object]

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/sphinx/cmd/build.py", line 337, in build_main
    app.build(args.force_all, args.filenames)
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/sphinx/application.py", line 378, in build
    self.builder.build_update()
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 296, in build_update
    self.build(to_build,
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 317, in build
    updated_docnames = set(self.read())
                           ^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 424, in read
    self._read_serial(docnames)
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 476, in _read_serial
    self.read_doc(docname)
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 535, in read_doc
    publisher.publish()
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/docutils/core.py", line 234, in publish
    self.document = self.reader.read(self.source, self.parser,
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/sphinx/io.py", line 106, in read
    self.parse()
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/docutils/readers/__init__.py", line 76, in parse
    self.parser.parse(self.input, document)
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/myst_nb/sphinx_.py", line 152, in parse
    with create_client(
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/myst_nb/core/execute/base.py", line 79, in __enter__
    self.start_client()
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/myst_nb/core/execute/cache.py", line 72, in start_client
    result = single_nb_execution(
             ^^^^^^^^^^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/jupyter_cache/executors/utils.py", line 58, in single_nb_execution
    executenb(
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/nbclient/client.py", line 1314, in execute
    return NotebookClient(nb=nb, resources=resources, km=km, **kwargs).execute()
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/jupyter_core/utils/__init__.py", line 165, in wrapped
    return loop.run_until_complete(inner)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/docs/.asdf/installs/python/3.12.3/lib/python3.12/asyncio/base_events.py", line 687, in run_until_complete
    return future.result()
           ^^^^^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/nbclient/client.py", line 693, in async_execute
    async with self.async_setup_kernel(**kwargs):
  File "/home/docs/.asdf/installs/python/3.12.3/lib/python3.12/contextlib.py", line 210, in __aenter__
    return await anext(self.gen)
           ^^^^^^^^^^^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/nbclient/client.py", line 648, in async_setup_kernel
    await self.async_start_new_kernel(**kwargs)
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/nbclient/client.py", line 550, in async_start_new_kernel
    await ensure_async(self.km.start_kernel(extra_arguments=self.extra_arguments, **kwargs))
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/jupyter_core/utils/__init__.py", line 198, in ensure_async
    result = await obj
             ^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/jupyter_client/manager.py", line 96, in wrapper
    raise e
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/jupyter_client/manager.py", line 87, in wrapper
    out = await method(self, *args, **kwargs)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/jupyter_client/manager.py", line 435, in _async_start_kernel
    kernel_cmd, kw = await self._async_pre_start_kernel(**kw)
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/jupyter_client/manager.py", line 397, in _async_pre_start_kernel
    self.kernel_spec,
    ^^^^^^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/jupyter_client/manager.py", line 195, in kernel_spec
    self._kernel_spec = self.kernel_spec_manager.get_kernel_spec(self.kernel_name)
                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/jupyter_client/kernelspec.py", line 285, in get_kernel_spec
    raise NoSuchKernel(kernel_name)
jupyter_client.kernelspec.NoSuchKernel: No such kernel named mesa_geo

Exception occurred:
  File "/home/docs/checkouts/readthedocs.org/user_builds/mesa-geo/envs/main/lib/python3.12/site-packages/jupyter_client/kernelspec.py", line 285, in get_kernel_spec
    raise NoSuchKernel(kernel_name)
jupyter_client.kernelspec.NoSuchKernel: No such kernel named mesa_geo
The full traceback has been saved in /tmp/sphinx-err-ycc8zhmq.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

Expected behavior

ReadtheDocs should build successfully.

To Reproduce

In the visual environment, install docs dependency:

pip install -e ".[dev]"

Then in the docs folder, run:

python -m sphinx -T -b html -d _build/doctrees -D language=en . html

Additional context

This is likely caused by

mesa-geo/docs/tutorials/intro_tutorial.ipynb

Lines 1112 to 1117 in 5b05dcd

	"metadata": {
	"kernelspec": {
	"display_name": "Xeus-Python (Python 3.10)",
	"language": "python",
	"name": "mesa_geo"
	},

I'm not sure whether removing these will have any side effects.

• (may not be useful) npsphinx has a nbsphinx_kernel_name parameter that can change kernel name: https://github.com/spatialaudio/nbsphinx/blob/ae3c9d9bbf56b6afe5f102f62cd14dfb44e76011/doc/configuring-kernels.ipynb#Kernel-Name

[wang-boyu]

Fixed by #229. Closing.