Restructuredtext in jupyter notebook text cells

Website https://nbsphinx.readthedocs.io/en/0.3.5/raw-cells.html displays the use of reST in jupyter notebook text cells. But jupyter notebooks on my computer do not behave in the way described in that website. How can I configure jupyter notebooks to have a cellbar with a reST option? I’m assuming that this would allow me to use reST in text cells.

Secondly, if I can configure this on my machine, will a jupyter notebook, written by me using reST, be readable/runnable by a user of another computer with a standard jupyter notebook configuration, that is, not specially set up for reST?

Hopefully someone can answer your questions; however, if you want to explore the answers yourself starting with “I’m assuming that this would allow me to use reST in text cells”, then you can go here press launch binder. Then in the session that comes up, click to edit the text in one of the markdown cells, and then using the menubar switch it to ‘Rar NBConvert’ format. Then to see ‘reST’ listed in the raw cell format toolbar, select from up along the File menu at the top select ‘View’ > ‘Cell Toolbar’ > ‘Raw Cell Format’.

You should then be able to edit the notebook with your restructured text content, save it, and then download it from the remote session to your machine. To test it in a machine that hasn’t had nbsphinx installed, you can launch into a new session with the classic Jupyter dashobard here and upload the notebook you downloaded to there to see how the machine renders it. (I’d advise against your own machine as the naive machine since it sounds like you already tried installing nbsphinx?)

1 Like

Very helpful comments.

I work with conda python virtual environments. My base environment does not have nbsphinx,
My base environment has the following jupyter components (output from conda list)
jupyter 1.0.0 py39hecd8cb5_7
jupyter_client 7.1.2 pyhd3eb1b0_0
jupyter_console 6.4.3 pyhd3eb1b0_0
jupyter_core 4.9.2 py39hecd8cb5_0
jupyterlab_pygments 0.1.2 py_0
jupyterlab_widgets 1.0.0 pyhd3eb1b0_1

My dev environment is suitable for making readthedocs and does include nbsphinx. This is how I saw the conflict between rendering for readthedocs and jupyter notebook. So I think I would just need to switch environments rather than use another computer. I’l try out what you say when I have a bit of time, and report back, since others may be interested (perhaps???).

1 Like

One of the issues here is that nbsphinx doesn’t support JupyterLab, the new notebook frontend. If you’re interested in moving to Jupyter/Retrolab, you could look into jupyterlab-myst (and the Executable Books project), which enables MyST rendering in JupyterLab. MyST is described here: it is a Markdown variant that is designed for writing technical documentation.

1 Like

FYI, I just released a fully re-written https://myst-nb.readthedocs.io (the underlying sphinx extension for jupyter-book).
Its a lot more powerful than nbsphinx :wink: (but just as easy to use)

1 Like