Using sphinx format does not convert markdown to rST

[MRegeard]

Hello,

I am trying to use jupytext to convert a jupyter notebook to a sphinx-gallery python script. I am using the following command : jupytext --to py:sphinx notebook.ipynb But then when I look at the output file, it seems that the markdown of the notebook are not converted to rST. Is this a know issue, or am I doing it wrong?

I am using jupytext version 1.14.5.

[MRegeard]

Let me correct myself. I think that it is only the header syntaxe in markdown which is not converted into header syntax in rST:

md :

# Title
## Section

should be converted to rST :

Title
=====
Section
-------

[mwouts]

Hello @MRegeard , thanks for asking. Well we don't support the conversion of Markdown to rST (only the opposite one actually, see https://jupytext.readthedocs.io/en/latest/formats.html#sphinx-gallery-scripts)

Out of curiosity, what would you think of using MyST Markdown rather than rST? I see that even readthedocs has a section on this: https://docs.readthedocs.io/en/stable/guides/migrate-rest-myst.html

[MRegeard]

Hello @mwouts, thanks for your response.

The thing is that we are using sphinx to generate our documentation (https://docs.gammapy.org/dev/). So I am pretty sure we need to use rST.

Is not supporting Markdown to rST conversion a choice or is it just not developed yet?

[mwouts]

I see.

Well there is no plan at all to convert Markdown to rST within Jupytext, because a) Jupyter Notebooks use Markdown, so we only need to support Markdown, and b) it would be probably too hard to provide a robust two-way conversion, and again that would not really belong to the scope of Jupytext.

The opposite conversion is supported as the Sphinx text notebooks were one of the few existing text notebook formats when the Jupytext project was started.

Now, I am not an expert in Sphinx, but this seems to be what you are looking for: https://myst-parser.readthedocs.io/en/v0.15.1/sphinx/intro.html. I mean, you could progressively start using MyST Markdown notebooks rather than rST notebooks, and there you would be able to use the Markdown/MyST Markdown syntax.