Download a documentation page as a Pluto notebook

[ChrisRackauckas]

For our tutorials using @examples and all, the content is all generated from Julia code. It would be really cool if you could download the Pluto notebook which then regenerates the page. The information for how to do so can be sourced from the Project/Manifest, since that gets the packages to build the page anyways, that's enough to be the image for the notebook. So in theory it's possible, it would just take a translation of the documenter page to Pluto, and a download button on pages that makes it easy to obtain.

[fredrikekre]

Would fredrikekre/Literate.jl#120 be useful?

Literate.jl can currently output Jupyter notebooks (and the Markdown files to Documenter). That setup is used e.g. here: https://ferrite-fem.github.io/Ferrite.jl/stable/examples/heat_equation/ where, at the top, you have a link to the corresponding Jupyter notebook, and at the bottom a link to the raw source: https://ferrite-fem.github.io/Ferrite.jl/stable/examples/heat_equation/#heat_equation-plain-program. All three outputs come from a single source file: https://github.com/Ferrite-FEM/Ferrite.jl/blob/master/docs/src/literate/heat_equation.jl

[ChrisRackauckas]

Why not bake it in as functionality to Documenter though? Make it one of the standard buttons on the top right? I like the Literate solution here, but I would like to have every Documenter page do this. I don't understand if it's a technical limitation that Literate's features here are separate, or if it just hasn't been upstreamed and for now lives separate.

[fredrikekre]

Most pages wouldn't be so interesting to download as a notebook since many pages (i.e. manual section and reference sections) don't even contain code. Downloading as a notebook seems more useful for standalone example pages and the like.

What I like with the Literate approach is that the source is a regular Julia source file. But of course you can go in the other direction and try to construct a notebook from a markdown page, but Literate already offers this (kind of) if you don't mind writing Julia code instead of Markdown files.

[ChrisRackauckas]

I'd prefer to have one system: less to teach and maintain. And if the button for the notebook is always in the same place for every documentation, then it's easy for people to find. Even if only a subset of pages will ever get downloaded, I think that consistency is very valuable in websites.

[mortenpi]

I don't understand if it's a technical limitation that Literate's features here are separate, or if it just hasn't been upstreamed and for now lives separate.

From my point of view, it's that it's a bit out of scope for Documenter, especially since we have a separate package that works and integrates well. Of course, this could be countered with a "Documenter should be batteries loaded" argument.

There also are a few design questions: how would you e.g. handle page cross-references and docstrings in the notebooks? I feel that, in general, you end up with half-broken notebooks most of the time if you just automatically convert all the pages. Hence and opt-in would be better.

[odow]

My 2c: I don't think this can or should live in Documenter.

In the JuMP tutorials, we have a "Download the source as a .jl file" https://jump.dev/JuMP.jl/stable/tutorials/getting_started/getting_started_with_julia/. You could just add that to the Pluto notebooks.