[SciPy-Dev] ways of storing notebook tutorials?

[Eric Larson]

I've used sphinx-gallery <https://sphinx-gallery.github.io/> in a number of
projects (am now a maintainer). Basically you write Python code
<https://github.com/mne-tools/mne-python/blob/master/tutorials/source-modeling/plot_eeg_mri_coords.py>
and it renders to html
<https://mne.tools/dev/auto_tutorials/source-modeling/plot_eeg_mri_coords.html>
with links to downloadable notebooks in the page, automatic
linking/cross-refs to function and class defs, nice index pages
<https://mne.tools/dev/auto_tutorials/index.html>, etc.

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.
>
> Cheers,
>
> Matthew
>
> On Tue, Oct 8, 2019 at 2:14 PM Ralf Gommers <ralf.gommers at gmail.com>
> wrote:
> >
> > Hi all,
> >
> > Christina is working on a nice scipy.optimize tutorial in notebook form.
> I like that in principle; Sphinx is not great for long-form tutorials. It
> does raise the question of how to integrate those notebooks. Notebooks with
> output in version control are quite problematic (size, unreadable diffs,
> breaking command line code search tools, etc.).
> >
> > I can think of a number of ways to start integrating notebooks, but I'd
> rather not reinvent this particular wheel. Are there recommendations for
> setups other projects have that work well? Pointers to discussions other
> projects have had on this topic would also be nice.
> >
> > Cheers,
> > Ralf
> >
> > _______________________________________________
> > 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/71839d07/attachment.html>