Writing executable Sphinx documentation with the myst-parser

[florian-wagner]

Dear all,

first of all thanks for the great work! @rowanc1 encouraged me to use this channel here.

We are currently discussing moving the pyGIMLi documentation to the myst-parser. One prerequisite for this is that the code snippets in the documentation are actually executable (potentially with doctest checks) and that figures generated by the code snippets are included in the documentation. From my perspective there are currently these options:

1. Use the sphinx-gallery extension, but this currently does not support the myst-parser: Support MyST markdown sphinx-gallery/sphinx-gallery#710
2. Use existing sphinx directives, such as the matplotlib or IPython directives, but they seem to have some existing incompatibilities with the myst-parser: sphinx-build fails with error when using ipython directive MyST-Parser#694
3. Include actual Python files or parts of it using the include directives.

All of these options are not ideal and I am wondering if I am missing something here.

Thanks for your insights!

Florian

[agoose77]

Hi @florian-wagner, thanks for opening this discussion!

In the Sphinx space, Executable Books developed (and maintain) the MyST-NB project. This package is responsible for ingesting notebook-like formats and handling the executable code blocks/embedded outputs in the file. It sounds like this is the tool that you need!
With myst-nb, you can author text-based notebooks that play nicely with VCS but are executed at build time.

One thing that I'm unsure of is whether you need doctest support? The workflow that I'm envisaging here is effectively "write your tests as notebooks", such that a test fails if it causes the notebook execution to fail (e.g. bare asserts). Actual doctest support is not something that MyST-NB supports yet.

[florian-wagner]

Thanks a lot Angus! I completely missded MyST-NB. That satisfies all our needs.