[SciPy-Dev] ways of storing notebook tutorials?

Tue Oct 8 14:26:14 EDT 2019

In case you haven't seen it Bokeh just tweeted this
https://twitter.com/BokehPlots/status/1181215112872509441

Maybe we can ask Bryan about the pros and cons.

On Tue, Oct 8, 2019 at 6:07 PM Shekhar Rajak <shekharrajak.1994 at gmail.com>
wrote:

> I agree that Jupyter notebook is better for writing long tutorials with
> output (images, graphs, different printing output).
>
> We can have a separate repository to write tutorials in IPython notebook
> for different topics and subtopics. It will be organized and new
> contributors can add their notebook tutorial about specific topic as well
> (maybe someone will come with solving really interesting real world
> problem).
>
> Once we have ipython notebook file then we can get the sharing link as
> well using : https://nbviewer.jupyter.org/, by just using the github URL
> of the ipython notebook file.
>
> For example IPython file:
> https://github.com/Shekharrajak/PyCon-SymPy-SymEngine/blob/master/SymPy_material/tutorial_exercises/01-Symbols-Derivatives-Functions.ipynb
>
> can be shared easily using nbviewer:
> https://nbviewer.jupyter.org/github/Shekharrajak/PyCon-SymPy-SymEngine/blob/master/SymPy_material/tutorial_exercises/01-Symbols-Derivatives-Functions.ipynb
>
> We also have binder option (
> https://mybinder.org/v2/gh/Shekharrajak/PyCon-SymPy-SymEngine/master?filepath=SymPy_material/tutorial_exercises/01-Symbols-Derivatives-Functions.ipynb)
> So then can run the same file in browser as well without installing and
> setting up anything new.
>
> So while writing about the topic in docs (.rst file or .md file), the
> writer can refer to the notebook nbviewer URL. The notebook content will be
> automatically updated whenever ipynb file is updated.
>
>
> Regards,
> Shekhar Prasad Rajak, <http://s-hacker.info/>
> Contact : +918142478937
> Blog <http://shekharrajak.github.io/> | Github
> <https://github.com/Shekharrajak> | Twitter
> <https://twitter.com/shekharrajak>
> Skype: shekhar.rajak1
>
>
>
> On Tuesday, 8 October 2019, 08:58:16 pm GMT+5:30, Andrew Nelson <
> andyfaff at gmail.com> wrote:
>
>
> Another alternative is to use `jupyter-sphinx` and `nbsphinx` sphinx
> extensions. You can include a link to the unexecuted notebook in RST (e.g.
> https://github.com/refnx/refnx/blob/master/doc/index.rst), and when the
> doc build occurs it'll execute the notebook + output as part of the run.
>
> On Tue, 8 Oct 2019, 17:06 Matthew Brett, <matthew.brett at gmail.com> wrote:
>
> Hi,
>
> On Tue, Oct 8, 2019 at 3:55 PM Ralf Gommers <ralf.gommers at gmail.com>
> wrote:
> >
> >
> >
> > On Tue, Oct 8, 2019 at 3:22 PM Eric Larson <larson.eric.d at gmail.com>
> wrote:
> >>
> >> I've used sphinx-gallery in a number of projects (am now a maintainer).
> Basically you write Python code and it renders to html with links to
> downloadable notebooks in the page, automatic linking/cross-refs to
> function and class defs, nice index pages, etc.
> >
> >
> > That doesn't really answer my question I think. The starting point is:
> notebooks are nice to write a long-form tutorial in, ReST is not. And
> sphinx-gallery is nice for a set of independent small to medium sized
> examples, but not the best fit for a long tutorial on a whole module (e.g.
> http://scipy.github.io/devdocs/tutorial/optimize.html).
>
> Right - I think sphinx-gallery is the right choice for these small
> examples and where you want to develop the tutorial in text.  It
> solves the ReST output nicely.
>
> >>
> >>
> >> Eric
> >>
> >>
> >> On Tue, Oct 8, 2019 at 9:20 AM Matthew Brett <matthew.brett at gmail.com>
> wrote:
> >>>
> >>> Hi,
> >>>
> >>> I use Jupytext all the time now, and I prefer the RMarkdown input
> >>> format to Jupytext.
> >>>
> >>> Jupytext can convert .ipynb files to .Rmd files, and saves notebooks
> >>> as both .ipynb and .Rmd.
> >>>
> >>> The workflow is pretty good - after installing Jupytext, you open your
> >>> .Rmd file in the notebook interface, and run anything you want, in the
> >>> standard interface.
> >>>
> >>> Then you save, if you need to, which saves to both .ipynb and .Rmd.
> >>>
> >>> You edit the .Rmd using your nice text editor.
> >>>
> >>> Then you can reload the notebook in Jupyter, with just a browser
> >>> refresh, to see the changes, and to run any extra code you've added.
> >>>
> >>> I then store the .Rmd files only, in version control, keeping the
> >>> .ipynb as outputs from the final build step.
> >
> >
> > Thanks, that sounds like a reasonable workflow. Seems like we can
> roundtrip notebook -> plain text format -> notebook.
>
> Right - exactly - and you can do that interactively, so you can save
> from the Jupyter interface, load in a text editor, save in the text
> editor and just reload the page in Jupyter to get the result.  It will
> even keep the outputs as long as you haven't done very substantial
> edits.
>
> > We'll still need to integrate that into the built html docs then, so the
> plain text format should be ReST. That doesn't seem supported yet:
> https://jupytext.readthedocs.io/en/latest/using-cli.html#testing-the-round-trip-conversion.
> Or am I missing something?
>
> No, that is (currently) a problem that I haven't been working on -
> because I'm using Markdown output documents like jupyter-book and
> bookdown.   One of my collaborators uses notebooks a lot and I was
> going to suggest to him that we have a separate site for the notebooks
> and the main docs, or at least, we build them separately, and perhaps
> combine them after building to HTML.    Maybe jupyter-book would help
> here?  Chris Holdgraf is the maintainer, and he's very responsive.
>
> Cheers,
>
> Matthew
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at python.org
> https://mail.python.org/mailman/listinfo/scipy-dev
>
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at python.org
> https://mail.python.org/mailman/listinfo/scipy-dev
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at python.org
> https://mail.python.org/mailman/listinfo/scipy-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20191008/828ab1cf/attachment-0001.html>