Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Download a documentation page as a Pluto notebook #1987

Open
ChrisRackauckas opened this issue Dec 6, 2022 · 6 comments
Open

Download a documentation page as a Pluto notebook #1987

ChrisRackauckas opened this issue Dec 6, 2022 · 6 comments
Labels
Format: HTML Related to the default HTML output Status: Speculative It's unknown if this is something that we wan't to do Type: Feature Type: Plugin A feature that should be implemented as a separate package.

Comments

@ChrisRackauckas
Copy link
Contributor

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
Copy link
Member

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
Copy link
Contributor Author

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
Copy link
Member

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
Copy link
Contributor Author

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 mortenpi added Type: Feature Status: Speculative It's unknown if this is something that we wan't to do Type: Plugin A feature that should be implemented as a separate package. Format: HTML Related to the default HTML output labels Dec 21, 2022
@mortenpi
Copy link
Member

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
Copy link
Collaborator

odow commented Nov 1, 2023

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Format: HTML Related to the default HTML output Status: Speculative It's unknown if this is something that we wan't to do Type: Feature Type: Plugin A feature that should be implemented as a separate package.
Projects
None yet
Development

No branches or pull requests

4 participants