Literate.jl format pairing

[pnavaro]

Literate.jl markdown format is very useful to include tutorial in Julia package documentation generated by Documenter.jl.
Unfortunately this format is not really made for editing. It already exists a converter from ipynb file. It could be nice if
jupytext allows to pair a notebook with Literate markdown.

Jupytext fixed the main drawback of Jupyter notebooks. Thank you very much.

[mwouts]

Hello @pnavaro , thanks for letting me know about Literate.jl. I just had a look at it, and it seems that the basics are well compatible with Jupytext's representation of notebooks as Julia scripts or Markdown documents.

Precisely, example.jl states that the basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. This is exactly the rule that jupytext follows when it opens a Julia script as a notebook.

The differences that I have seen are

• Literate.jl allows to filter out lines depending on the output using the #md, #nb, #jl and #src - Jupytext does that with the active cell metadata
• Literate.jl allows to capture outputs - Jupytext does not.

From what I have seen, the representation of Literate.jl document as Markdown documents seems again well compatible with Jupytext's representation of notebooks as Markdown documents.

Now, can you describe a bit further what are your expectations for the pairing between Jupyter notebooks and Julia scripts? Or Markdown documents? Which feature are you missing now?

And maybe we should also invite @fredrikekre to join this conversation, he will surely have interesting remarks. Also, see how a sample Julia Jupyter notebook is represented as a Markdown document or as a Julia script using Jupytext.

[pnavaro]

I use Literate.jl to provide some examples of Julia. From this Literate.jl file you can generate the
markdown file used to generate documentation with Documenter.jl and also an ipynb file you can
provide as tutorial. Unfortunately the Literate.jl is not easy to edit. Usually I open a Jupyter notebook and convert the ipynb file to Literate.jl format with https://github.com/oxinabox/WeaveAwayNotebooks. Open and modify the Literate.jl format file with Jupyter and Jupytext will be much easier.

[mwouts]

Open and modify the Literate.jl format file with Jupyter and Jupytext will be much easier.

Sure. Did you try that? I would have expected it to work. With Jupytext, every .jl or .md file opens as a notebook in Jupyter Notebook. In Jupyter Lab, right-click on the file and select open with Notebook. And if you want to preserve the outputs, pair the script/Markdown document with an ipynb document (this is now possible directly in Jupyter Notebook, see #213, otherwise on the command line that's jupytext --set-formats ipynb,md --sync file.md).

[pnavaro]

When i save the Literate.jl file.jl with jupytext it breaks the format by inserting some spaces.
"#md" becomes "# md". Thanks for your help

[pnavaro]

I think i can fix these minor changes with a few lines of code during the documentation processing.
Thanks!

[fredrikekre]

Unfortunately the Literate.jl is not easy to edit.

I guess that is subjective, I, for one, really dislike editing notebooks and much prefer a plain text file representation, also when editing :)

It is not immediately clear to me what issue you are having, is it:

When i save the Literate.jl file.jl with jupytext it breaks the format by inserting some spaces.
"#md" becomes "# md".

?

I will try to install jupytext later and play around a bit.

[pnavaro]

If you have a lot of markdown text in the file, it is not easy because everything is commented out.
I still don't know which format i should use : Literate jl format or Weave jmd format. Both are good that's the problem :-D

[mwouts]

I will try to install jupytext later and play around a bit.

Thanks @fredrikekre . I'd be happy to help and to improve the compatibility of Jupytext with existing tools.

I still don't know which format i should use : Literate jl format or Weave jmd format. Both are good that's the problem

@mpastell, I followed the links above and see that you also have experience with notebooks as .jl files or .jmd notebooks. Please let me know if you'd like to see the .jmd extension supported in Jupytext (question: is there any difference with the current Jupytext's .md representation of notebooks?)

[pnavaro]

The .jmd files are almost the same . There is just a header at the top of the file

---
title: Example
author: Pierre Navaro
---

Math equations are also defined with

```math
...
```

instead of

 $$ 
... 
$$