Have markdown cells in exported notebooks

[dvarjas]

If I download an example notebook, it only has code cells without any comments, which makes using these examples hard.

[jbweston]

This seems complicated because we would need to convert arbitrary ReST to a markdown cell, but maybe there's some heuristic we can use

[akhmerov]

We could optionally integrate with pandoc.

[akhmerov]

sphinx-gallery just inserts rst content into the notebooks, we can add a global configurable whether to add the rst contents inside the notebooks.

As an improvement over that, we could include pandoc to generate proper markdown.

[basnijholt]

This would also be very useful for Adaptive, where we have an example notebook. Ideally, we should be able to use content from the docs to generate the notebook.

[AdriaanRol]

I am facing this same issue in quantify, having the tutorial notebooks contain the .rst would be very helpful.

[12rambau]

I don't know what was the status of nbsphinx and myst-nb in 2019 but before I start working on this one I would like to know if it's still a wanted feature.

Jupyter-sphinx is very good at what it does: displaying executed jupyter cells from a .rst documentation page. nbsphinx and myst-nb on the other hand are very good at something else: displaying jupyter notebooks as documentation pages.

instead of reinventing the wheel wouldn't it be more interesting to directly code a notebook from the start instead of transforming a .rst source into it ?

[basnijholt]

Because of this missing feature I have converted most of the Sphinx documentation sites I maintain to myst-nb, which works very nicely with Jupytext Markdown notebooks.

Would this feature have been implemented I would likely not have switched.

Somewhere around 2015 we (me and @jbweston) actually tried implementing this feature in jupyter-sphinx, but we realized it would be quite difficult because a lot of the Sphinx features do not translate well to Jupyter Notebooks.

[akhmerov]

jupyter-sphinx allows to directly include executable code anywhere in the sphinx doctree. This is more general than the notebook structure, where executable code may only occur as a top level entry. The executablebooks stack implements a different approach of linking a cell from different places of its markup. There were also community discussions about linking cell outputs in the inline markup, but as far as I know, the result is inconclusive.

Additionally, many elements of a sphinx doctree have no native representation in Jupyter markdown. Myst implements its own renderer in a jupyterlab extension, but this is a major effort as far as I understand.

A possible way, but a rather complex way forward could be:

• Using https://github.com/executablebooks/rst-to-myst for converting the source to myst
• Using myst features for linking cell outputs in the markup (glue)

Previously in this thread, a quick-and-dirty approach of dumping the document source into the notebook was discussed as an alternative.

Ultimately I am unsure whether this feature is worth the effort, compared to the options myst-nb and nbsphinx provide.