search

danielfrg / mkdocs-jupyter

Use Jupyter Notebook in mkdocs
https://mkdocs-jupyter.danielfrg.com
Apache License 2.0
385 stars 47 forks source link

Simplest example doesn't work; simple workaround #154

Closed moble closed 1 year ago

moble commented 1 year ago

I tried the simplest possible example, and it fails with

jinja2.exceptions.TemplateNotFound: mkdocs_html/notebook.html.j2

The full traceback is below. The very first thing is a deprecation warning that says something about Jupyter migrating its paths, and mentions setting JUPYTER_PLATFORM_DIRS=1. It turns out that without this, mkdocs will fail. That is, you can just run

JUPYTER_PLATFORM_DIRS=1 mkdocs build

or

JUPYTER_PLATFORM_DIRS=1 mkdocs serve

and it will work.

Here's the full traceback

> mkdocs build
INFO     -  DeprecationWarning: Jupyter is migrating its paths to use standard platformdirs
            given by the platformdirs library.  To remove this warning and
            see the appropriate new directories, set the environment variable
            `JUPYTER_PLATFORM_DIRS=1` and then run `jupyter --paths`.
            The use of platformdirs will be the default in `jupyter_core` v6
              File ".../envs/mkdocs_jupyter/lib/python3.11/site-packages/jupyter_core/utils/__init__.py", line 89, in deprecation
                warnings.warn(message, DeprecationWarning, stacklevel=stacklevel + 1)
              File ".../envs/mkdocs_jupyter/lib/python3.11/site-packages/jupyter_client/connect.py", line 20, in
                from jupyter_core.paths import jupyter_data_dir, jupyter_runtime_dir, secure_write
INFO     -  DeprecationWarning: pkg_resources is deprecated as an API
              File ".../envs/mkdocs_jupyter/lib/python3.11/site-packages/jupytext/cell_reader.py", line 14, in <module>
                from pkg_resources import parse_version
              File ".../envs/mkdocs_jupyter/lib/python3.11/site-packages/pkg_resources/__init__.py", line 121, in <module>
                warnings.warn("pkg_resources is deprecated as an API", DeprecationWarning)
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: /home/moble/tmp/mkdocs-jupyter-test/site
INFO     -  Converting notebook (execute=False): /home/moble/tmp/mkdocs-jupyter-test/docs/demo-script.py
ERROR    -  Error reading page 'demo-script.py': mkdocs_html/notebook.html.j2
Traceback (most recent call last):
  File ".../envs/mkdocs_jupyter/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
             ^^^^^
  File ".../envs/mkdocs_jupyter/lib/python3.11/site-packages/click/core.py", line 1130, in __call__
    return self.main(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../envs/mkdocs_jupyter/lib/python3.11/site-packages/click/core.py", line 1055, in main
    rv = self.invoke(ctx)
         ^^^^^^^^^^^^^^^^
  File ".../envs/mkdocs_jupyter/lib/python3.11/site-packages/click/core.py", line 1657, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../envs/mkdocs_jupyter/lib/python3.11/site-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../envs/mkdocs_jupyter/lib/python3.11/site-packages/click/core.py", line 760, in invoke
    return __callback(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../envs/mkdocs_jupyter/lib/python3.11/site-packages/mkdocs/__main__.py", line 250, in build_command
    build.build(cfg, dirty=not clean)
  File ".../envs/mkdocs_jupyter/lib/python3.11/site-packages/mkdocs/commands/build.py", line 308, in build
    _populate_page(file.page, config, files, dirty)
  File ".../envs/mkdocs_jupyter/lib/python3.11/site-packages/mkdocs/commands/build.py", line 181, in _populate_page
    page.render(config, files)
  File ".../envs/mkdocs_jupyter/lib/python3.11/site-packages/mkdocs_jupyter/plugin.py", line 108, in new_render
    body = convert.nb2html(
           ^^^^^^^^^^^^^^^^
  File ".../envs/mkdocs_jupyter/lib/python3.11/site-packages/mkdocs_jupyter/nbconvert2.py", line 132, in nb2html
    content, resources = exporter.from_file(
                         ^^^^^^^^^^^^^^^^^^^
  File ".../envs/mkdocs_jupyter/lib/python3.11/site-packages/nbconvert/exporters/templateexporter.py", line 394, in from_file
    return super().from_file(file_stream, resources, **kw)  # type:ignore
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../envs/mkdocs_jupyter/lib/python3.11/site-packages/nbconvert/exporters/exporter.py", line 220, in from_file
    return self.from_notebook_node(
           ^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../envs/mkdocs_jupyter/lib/python3.11/site-packages/nbconvert/exporters/html.py", line 234, in from_notebook_node
    return super().from_notebook_node(nb, resources, **kw)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../envs/mkdocs_jupyter/lib/python3.11/site-packages/nbconvert/exporters/templateexporter.py", line 426, in from_notebook_node
    output = self.template.render(nb=nb_copy, resources=resources)
             ^^^^^^^^^^^^^
  File ".../envs/mkdocs_jupyter/lib/python3.11/site-packages/nbconvert/exporters/templateexporter.py", line 163, in template
    self._template_cached = self._load_template()
                            ^^^^^^^^^^^^^^^^^^^^^
  File ".../envs/mkdocs_jupyter/lib/python3.11/site-packages/nbconvert/exporters/templateexporter.py", line 382, in _load_template
    return self.environment.get_template(template_file)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../envs/mkdocs_jupyter/lib/python3.11/site-packages/jinja2/environment.py", line 1010, in get_template
    return self._load_template(name, globals)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../envs/mkdocs_jupyter/lib/python3.11/site-packages/jinja2/environment.py", line 969, in _load_template
    template = self.loader.load(self, name, self.make_globals(globals))
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../envs/mkdocs_jupyter/lib/python3.11/site-packages/jinja2/loaders.py", line 575, in load
    raise TemplateNotFound(name)
jinja2.exceptions.TemplateNotFound: mkdocs_html/notebook.html.j2

I created a fresh env and ran

python -m pip install mkdocs-jupyter

My mkdocs.yml looks like this:

site_name: mkdocs-jupyter

nav:
  - Home: index.md
  - A .py file (jupytext): demo-script.py

plugins:
  - mkdocs-jupyter

The index.md is trivial. When I comment out the plugins section and run mkdocs build, it works just fine.

danielfrg commented 1 year ago

This should be fixed in newer versions.

moble commented 1 year ago

This should be fixed in newer versions.

Maybe, at some point, once jupyter_core releases version 6. But there doesn't even seem to be a timeframe for that yet. For now, I can verify that the most recent versions of everything still result in the error above, so the workaround is still needed.