This versions see's many great changes; utilising the ⬆️ upgrade to `myst-parser=v0.12`
and accompanying ⬆️ upgrade to `sphinx=v3`,
as well as major refactors to the execution ([236](https://github.com/executablebooks/MyST-NB/commit/2bc0c11cedbad6206f70546819fad85d779ce449)) and code output rendering ([#243](https://github.com/executablebooks/MyST-NB/commit/04f3bbb928cf1794e140de6a919fb58578753300)).
Plus much more configuration options, to allow for a more configurable workflow (the defaults work great as well!).
Below is a summary of the changes, and you can also check out many examples in the documentation, <https://myst-nb.readthedocs.io/>,
and the MyST-Parser Changelog for all the new Markdown parsing features available: <https://github.com/executablebooks/MyST-Parser>.
New ✨
- Custom notebook formats:
Configuration and logic has been added for designating additional file types to be converted to Notebooks, which are then executed & parsed in the same manner as regular Notebooks.
See [Custom Notebook Formats](https://myst-nb.readthedocs.io/en/latest/examples/custom-formats.html) for details.
- Allow for configuration of render priority (per output format) with `nb_render_priority`.
- The code cell output renderer class is now loaded from an entry-point, with a configurable name,
meaning that anyone can provide their own renderer subclass.
See [Customise the render process](https://myst-nb.readthedocs.io/en/latest/use/formatting_outputs.html#customise-the-render-process) for details.
- Assignment of metadata tags `remove-stdout` and `remove-stderr` for removal of the relevant outputs ([see here](https://myst-nb.readthedocs.io/en/latest/use/formatting_outputs.html#removing-stdout-and-stderr))
- Render `text/markdown` MIME types with an integrated CommonMark parser ([see here](https://myst-nb.readthedocs.io/en/latest/use/formatting_outputs.html#markdown)).
- Add code output image formatting, *via* cell metadata, including size, captions and labelling ([see here](https://myst-nb.readthedocs.io/en/latest/use/formatting_outputs.html#images)).
- Notebook outputs ANSI lexer which is applied to stdout/stderr and text/plain outputs, and is configurable *via* `nb_render_text_lexer` ([see here](https://myst-nb.readthedocs.io/en/latest/use/formatting_outputs.html#ansi-outputs)).
- Capture execution data in sphinx env, which can be output into the documentation, with the `nb-exec-table` directive. See [Execution statistics](https://myst-nb.readthedocs.io/en/latest/use/execute.html#execution-statistics) for details.
Improved 👌
- Standardise auto/cache execution
Both now call the same underlying function (from `jupyter-cache`) and act the same.
This improves `auto`, by making it output error reports and not raising an exception on an error.
Additional config has also been added: `execution_allow_errors` and `execution_in_temp`.
As for for `timeout`, `allow_errors` can also be set in the notebook `metadata.execution.allow_errors`
This presents one breaking change, in that `cache` will now by default execute in a the local folder as the CWD (not a temporary one).
Fixed 🐛
- Code cell source code is now assigned the correct lexer when using custom kernels ([39c1bb9](https://github.com/executablebooks/MyST-NB/commit/39c1bb99e73b35812474366f2f1760850fe40a57))
Documented 📚
- Add example of using kernels other than Python ([676eb2c](https://github.com/executablebooks/MyST-NB/commit/676eb2c46b1ca605980180479c845b43ec64c5fb))
Refactored ♻️
- Add more signature typing and docstrings
- Move config value validation to separate function
- Rename functions in cache.py and improve their logical flow
- Rename variable stored in sphinx environment, to share same suffix:
- `path_to_cache` -> `nb_path_to_cache`
- `allowed_nb_exec_suffixes` -> `nb_allowed_exec_suffixes`
- `excluded_nb_exec_paths` -> `nb_excluded_exec_paths`
- Initial Nb output rendering:
- Ensure source (path, lineno) are correctly propagated to `CellOutputBundleNode`
- Capture cell level metadata in `CellOutputBundleNode`
- New `CellOutputRenderer` class to contain render methods
- Simplify test code, using sphinx `get_doctree` and `get_and_resolve_doctree` methods