Using HTML export of Pluto within Documenter.jl

[kellertuer]

I was listening to Fons great talk at this JuliaCon and was wondering whether one could user Pluto-Notebook exports within the documentation of a package.

Currently I have plain examples in the repository ( Manopt.jl that is) and elaborate Literate.jl Tutorials that I pre-render into markdown at the beginning of the make.jl of the documentation.

I would like to to something like that with the Pluto-html-export. My idea is as follows

• replace the example and Literate code with one Pluto notebook
• in the make.jl trigger an evaluation and export of the notebook to html and store it in the assets/ of the documentation
• have a markdown file that includes this html as a page into the documentation.

The only point I am not so sure about is the rendering/export call from make.jl – would that be possible? And if it is not possible, what I missing and can I help somewhere?

[Ellipse0934]

The generate_html function (here) should be of help.

Example:

 s = Pluto.ServerSession();
nb = Pluto.SessionActions.open(s, nb_path; run_async=false)
html_contents = Pluto.generate_html(nb; binder_url_js="undefined")

[kellertuer]

Sorry for the delay, this looks nice, I will try this as soon as I have finished my first example in Pluto :)

[kellertuer]

So the approach mentioned here works locally on my machine – not yet on CI, but I am nearly there, see

https://manoptjl.org/previews/PR94/pluto/AutomaticDifferentiation.html

for a first export and

https://github.com/JuliaManifolds/Manopt.jl/blob/dffd4312cb329ea2885cc88ca673a377dd842598/docs/make.jl#L40-L70

for the current approach.
Note that the Javascript for resize does not work locally (but it works after deployment) and the rendering currently (as mentioned) does work locally but on CI it seems to not load the required packages.

Edit: ad the height computation seems to also be done too early and the page is a little too small.

[kellertuer]

I managed to get it running, here is the result

https://manoptjl.org/stable/pluto/AutomaticDifferentiation.html

The few caveats

• The approach mentioned above does not seem to work with the new package manager, so I switched back to using Pkg and adding the required packages (in a hidden cell) before the using
• currently the height of the iFrame is hardcoded (to 370rem by trial and error),, and automated way or even better something without an iFrame would be cool
• This does not (yet) work nicely together with Darkmode in the docs.

[manuelbb-upb]

Hi,
concerning the iFrame height you might want to have a look at what I have done in these docs..

I have copied iFrame Resizer into docs/src/custom_assets and my make.jl does 3 things:
(i) Generate html from the julia notebooks (although I use PlutoSlideServer because I have not known about generate_html -- thanks for the hint!)
(ii) Insert a link to the javascript:

function modify_notebook_html( html_name )
    content = open( html_name, "r" ) do html_file 
        read( html_file, String )
    end
    content = replace(content, 
        r"(<script\b[^>]*>[\s\S]*?<\/script>)" => 
        s"\1\n\t<script src='./iframeResizer.contentWindow.min.js'></script>\n";
        count = 1
    )
    open( html_name, "w" ) do html_file
        write( html_file, content )
    end
    return nothing
end

(iii) Create markdown/html files that look like this:

<iframe id="fdnotebook" src="../custom_assets/notebook_finite_differences.html" width="100%"></iframe>
<script>
  const iFrameResizerPath = '../custom_assets/iframeResizer.min.js';

  if (require) {
    require([iFrameResizerPath], (iFrameResize) => iFrameResize())
  } else {
    const script = document.createElement('script')
    script.onload = () => iFrameResize()
    script.src = iFrameResizerPath
}
</script>
<script>
  document.addEventListener('DOMContentLoaded', function(){
    var myIframe = document.getElementById("fdnotebook");
    iFrameResize({log:true}, myIframe);	
});
</script>

All my functions are defined in this file.
Note, that the repository is expecting a major release, so that things might get tidied up a bit soon.

[kellertuer]

Neat! I currently look into the PlutoStaticHTML.jl, since it adapts better to dark mode for example.

Edit: See here https://manoptjl.org/previews/PR98/pluto/AutomaticDifferentiation/ for a current version that seems to be running (after some help by Rik)

[manuelbb-upb]

Oh, that look's great (and well integrated with Documenter). Thanks for the tip!
I might consider switching when I find the time (to improve loading and generation speed).

However, It appears the syntax highlighting is off?

[kellertuer]

That depends. For the input cells it is fine, for the output - it seems to be complicated.

[theogf]

If you are using Documenter.jl, you can also remove this line :

<script>
  const iFrameResizerPath = '../custom_assets/iframeResizer.min.js';

  if (require) {
    require([iFrameResizerPath], (iFrameResize) => iFrameResize())
  } else {
    const script = document.createElement('script')
    script.onload = () => iFrameResize()
    script.src = iFrameResizerPath
}
</script>

and add the following to makedocs instead.

makedocs(...; format=Documenter.HTML(assets=["assets/iFrameResizer"]))

Also regarding the Regex

r"(<script\b[^>]*>[\s\S]*?<\/script>)"

can be replaced by

r"(<script\b[^>]*>[\s\S]*?<\/script>\K)"

to avoid replacing a useful script file!

[mmikhasenko]

@kellertuer could you please share experience, what worked with Pluto documentation, what did not?
I see here you had nearly entirely documentation built with Pluto. I am tempted to do it for a couple of repositories, which are collections of Pluto notebooks.

[kellertuer]

As you can see here the „had“ is the right time. and for now I moved to Quarto hoping that those notebooks one day can be pandoced to Pluto notebooks.

I had two problems – one is, that Pluto is Markdown+Code while Documenter is as well. So it feels strange to have interns HTML. Quarto turns Markdown+Code into Markdown+Code+Markdown-output. That feels more natural.
My second problem was that the rendering was a bit slow and not that consistent. Sure for now Quarto is pre-rendered (committed rendered results), but that is what I already switched to with the previous solution as well. In the long run I would love to have a GitHub-Action+Cache solution for Quarto.
And if – again – Quarto->Pluto is a transform pandoc supports, maybe also that, such that the docs can link to Pluto Notebooks for the user to try themselves. That is maybe the only thing I miss for now.

[mmikhasenko]

I see, thanks for sharing the experience.

What do you mean with Markdown+Code+Markdown-output?

[kellertuer]

That this (Markdown + Code, including a folder-based environment) is rendered to this.