search

jupyter / jupyter-sphinx

Sphinx extension for rendering of Jupyter interactive widgets.
https://jupyter-sphinx.readthedocs.io/
BSD 3-Clause "New" or "Revised" License
188 stars 65 forks source link

Proposal: Notebook scripts to rst converter for sphinx #187

Open caenrigen opened 3 years ago

caenrigen commented 3 years ago

Hi guys!

Hope to find you well :)

I have developed a sphinx extensions that uses jupyter-sphinx + jupytext to solve the problem of having to constantly copy-paste code from a notebook into an .rst file when developing tutorials and docs (besides a few other advantages over the nbsphinx alternative). So I am creating this issue to ask if you would be interested in making it part of the jupyter-sphinx itself since it tightly depends on it.

I invite you to have a look at the documentation and its code. The documentation contain a fair bit of details/limitations/usage/template/etc..

There is room for improvements of course but it is already pretty usable. A bunch of examples of .py files that this extensions gets as input can be found here.

Looking forward to hear from you :)

@akhmerov

@AdriaanRol FYI

akhmerov commented 3 years ago

Hey @caenrigen, looks very interesting! As a quick note: https://jupyterbook.org/ is another related project, in addition to nbsphinx.

However as I understood from you, your goal is to allow code editing in a notebook environment with executable code nested in other rst directives. Is that right?

caenrigen commented 3 years ago

Hey @caenrigen, looks very interesting! As a quick note: https://jupyterbook.org/ is another related project, in addition to nbsphinx.

Hi Anton, thank you for the reply and resource.

I did not look into the jupyterbook project before, seems cool as well. Nonetheless, I am trying to keep it as simple as possible and easy to debug. Specially for people that just joined or want to contribute to a python project it can be intimidating to learn a lot of extra tools and markdown flavors.

However as I understood from you, your goal is to allow code editing in a notebook environment with executable code nested in other rst directives. Is that right?

Yes indeed, you spotted it well. It has this flexibility that I think I have not seen easily achieved with any other toolbox.