How to convert restructured text (.rst file) to jupyter notebook (.ipynb file)?
I have searched and tried the package rst2ipynb, but running the command rst2ipynb causes Windows to ask me "open with ...". I don't know other options. I prefer to use Jupyter's official solutions, because I know rst file is one of the natively supported formats that Jupyter supports.
sphinxcontrib.jupyterAs suggested by the rst2ipynb developer here.
"A better approach would be to implement a proper Jupyter-export extension for Sphinx.
NEWS (2017-10): you may want to explore the recent https://github.com/QuantEcon/sphinxcontrib-jupyter/ that does just this."
That tool has a section covering 'Usage in RST Files' that says "minimum configured sphinx repo is available here which generates a sample notebook".
That repository is sphinxcontrib-jupyter.minimal. And because it is all set up, you can easily plug into that for processing the conversions of your own .rst files.
This makes it easier because the configuration conf.py is already set up to convert any .rst file in the same directory to an .ipyn file when make jupyter is run.
sphinxcontrib-jupyter.minimalStart up a remote, temporary Jupyter session with the content of 'sphinxcontrib-jupyter.minimal'.
Go here and click 'Launch binder'.
Use the Launcher pane to open a terminal in the Jupyter session.
In the terminal, run:
git clone https://github.com/QuantEcon/sphinxcontrib-jupyter.minimal.git
cd sphinxcontrib-jupyter.minimal/
(The cd line above will change the terminal working directory to be in the sphinxcontrib-jupyter.minimal directory. This only affects the terminal and not the rest of Jupyter, for now.)
Install Sphinx and the extension.
Run in the terminal
pip install sphinxcontrib-jupyter
Navigate into the sphinxcontrib-jupyter.minimal directory in Jupyter's file navigation panel to prepare to add your own .rst file that will be converted.
To go into the sphinxcontrib-jupyter.minimal double-click on it in the file navigation pane, and you notice the indicator of the level in the hierarchy just above where you clicked will change to indicate where you are now.
In the sphinxcontrib-jupyter.minimal directory there is already two .rst files that these steps will convert. You should add your own to convince yourself it works with any .rst file.
Drag-and-drop from your local computer your .rst file to convert into file navigation pane on the left side of the Jupter session window. It will upload the file to the remote session.
My test file was this README.rst:
https://github.com/RunestoneInteractive/RunestoneComponents/blob/master/README.rst
I downloaded the raw code of that README file and renamed it RunestoneComponents.rst.
You should be ready to run the conversion process now. Any .rst file in that sphinxcontrib-jupyter.minimal directory will be converted in the next step.
.rst filesRun in the terminal
make jupyter
Importantly, as noted at the bottom of the text here:
"Generated notebooks can be found in the
_build/jupyter/folder."
Use the file navigation pane on the left and go into that _builddirectory and then the jupyter subdirectory and then you can click to open the converted notebooks.
Or you can right-click and use Open with... to handle as you see fit.
The session is temporary so in the file navigation pane, right-click and choose to download back to your local computer any useful notebook file you make on the remote session.
You'll see the result of the simple_notebook.rst conversion isa much more full-featured example converted notebook file. and you can use that to guide you in how to adjust your .rst input if necessary.
Alternatively, there is rst2ipynb...
rst2ipynb to convert step-by-stepStart up a remote, temporary Jupyter session by going here and clicking 'Launch binder'.
Use the Launcher pane to open a terminal in the Jupyter session.
Install pandoc as suggested here
In the terminal, type:
conda install -c conda-forge pandoc -y
Next, install rst2ipynb.
In the same terminal, run:
git clone https://github.com/nthiery/rst-to-ipynb.git
cd rst-to-ipynb
pip install .
cd ..
The last command just goes back up a level in the directory hierarchy.
Drag-and-drop from your local computer your .rst file to convert into file navigation pane on the left side of the Jupter session window. It will upload the file to the remote session.
My test file was this README.rst:
https://github.com/RunestoneInteractive/RunestoneComponents/blob/master/README.rst
I downloaded the raw code of that README file and renamed it RunestoneComponents.rst.
In terminal, I ran:
rst2ipynb RunestoneComponents.rst -o test.ipynb
Substitute the file name of your .rst file for RunestoneComponents.rst. Make the test.ipynb name whatever you want.
Double click on the created .ipynb file in the file navigation pane and it will open as a notebook in the session. You can right-click to choose Open With... options if you prefer.
The session is temporary so in the file navigation pane, right-click and choose to download back to your local computer any useful notebook file you make on the remote session.
rst2ipynb comes with its own test content you can convert, too.
rst2ipynb rst-to-ipynb/tests/all.rst -o all_test.ipynb
You'll see this results in a much more full-featured example converted notebook file. and you can use that to guide you in how to adjust your .rst input if necessary.
rst2ipynb conversion worked:You'll note the text there after, "This is currently achieved by", nicely outlines the process I suggested in my comments:
"This is currently achieved by converting to markdown using pandoc and then to a Jupyter notebook ..."
Other alternatives probably exist these days...
These days for working with reStructuredText there is a way to migrate from reStructuredText to MyST Markdown that works with Jupyter Books. And Jupyter Books do allow using because they Sphinx under the hood, see here. And so there may well be a way using all that but I didn't see it written out concisely like the other two I highlight above.
Similar for Quarto.
If I come across something, I'll try to update this section
