Documenter.jl: some (markdown) page <-> Jupyter notebooks conversion?

[Datseris]

(Consider this as a very far fetched feature request)

Would it be possible to create pages out of Jupyter notebooks? This would allow having an all-in-one documentation but still run some notebooks on e.g. JuliaBox without having to duplicate the effort of:

• creating a notebook
• creating a very similar documentation page

Maybe there is some simple way to convert a notebook into markdown that already exists somewhere?

---

Answer: yes, here https://nbconvert.readthedocs.io/en/latest/ is a way to convert notebooks to markdown files. Then, when running Travis, you can also install this, do the procedure for all notebooks, copy the notebooks to a specific folder and then run the make docs command.

I am leaving this open because I think it is cool and you (or I) could add it to the documentation. When (and If) I get it working I try to do a PR!

---

EDIT: As pointed out by Kristoffer, it is better to convert from markdown to Jupyter. As showed by Evizero, this is actually possible.

[KristofferC]

FWIW, I think rendering to notebooks from markdown is a better strategy since notebooks are not very version control friendly.

[Datseris]

@KristofferC I am not familiar on how to do this, can you please point me to a tutorial/example?

[KristofferC]

You could look at https://github.com/mpastell/Weave.jl or https://github.com/aaren/notedown. My point is, notebooks are a more "rich" target so it is likely simpler to to have them as output targets than as "source code".

[Evizero]

I implemented a hacky way of creating documentation pages as well as pre-executed jupyter notebooks from .jl scripts of the examples/ folder.

code: https://github.com/Evizero/Augmentor.jl/tree/master/docs

Feel free to just copy and change whatever, if you feel like it. That said, I am unsure if you want to go through the trouble of making this work for your use-case though as its not a clean solution.

Pretty happy with the result though. even have a link to the jupyter notebook from the docs

here is an example to see what the result is:
the source script: https://github.com/Evizero/Augmentor.jl/blob/master/examples/mnist_knet.jl
generated docs: https://evizero.github.io/Augmentor.jl/generated/mnist_knet/
generated notebook: (see button in docs in the top right corner)

[Datseris]

My point is, notebooks are a more "rich" target so it is likely simpler to to have them as output targets than as "source code".

Yes of course I completely agree, I just did not know it was possible.

@Evizero This amazing, and the end result is definitely what I was aiming for as well!!! But it seems quite complicated at the moment. When I have more free time I will have to "study" it if I want to apply it.

But maybe your approach can also be refined and implemented here in Documenter.jl as a full feature!

[mortenpi]

In order to not make Documenter explode with features, I am thinking it might be best to have this as a separate package/plugin. But it might be easiest to have this prototyped in Documenter's code first, and then see what it would take to split it into a separate package, making the necessary refactorings of Documenter's internals along the way.

[fredrikekre]

I put together https://github.com/fredrikekre/Literate.jl

It is a combination of some ideas from Weaver.jl, the code @Evizero showed and some local code I had for the same purpose. It is very WIP, 0% test coverage, but pretty well documented I think (https://fredrikekre.github.io/Literate.jl/latest/). Would be nice if someone would like to try it out.

[Datseris]

Thanks so much @fredrikekre for this. Seems easy to use and well laid out. I will incorporate it in my documentation, some time "soon". I will definitely report here as well how good it went and if I can come across improvements/issues/etc. I will post an issue at the repo!

[Evizero]

@fredrikekre Awesome to see how you took this to the next level

[Nosferican]

I think the idea is to have one convenient way to convert from markdown like to HTML, TeX, and IPYNB while supporting a variety of features:

• Citation management
• Equation / math
• Syntax highlight
• Cross-reference
  etc.

The Pythonic way of using RST is a bit too separate from script to my liking.