[SciPy-Dev] ways of storing notebook tutorials?

[Ralf Gommers]

On Tue, Oct 8, 2019 at 3:22 PM Eric Larson <larson.eric.d at gmail.com> wrote:

> 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.
>

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).


>
> 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. 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?

Cheers,
Ralf


>> 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
>>
> _______________________________________________
> 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/6e59e62a/attachment-0001.html>