Generation of documentation is very slow because of Pluto

[natema]

    Is Pluto the best thing for tutorials? 

Originally posted by @Dsantra92 in https://github.com/CarloLucibello/GraphNeuralNetworks.jl/issues/168#issuecomment-1170477427

It looks like the Pluto notebooks are responsible for making the local rendering of the documentation using LiveServer very long... Is there a clear desire to keep them or are you open to translating them into more classical tutorials, with the code directly displayed in documentation pages?

[CarloLucibello]

Yes that's annoying. Maybe the best thing would be to cache the generated markdown/html and recompile it only when needed. I think @Dsantra92 looked a bit into it but there were some problems. If the slowness cannot be solved I would be open to alternatives.

[aurorarossi]

I agree. Here a tutorial took 5 minutes:

[CarloLucibello]

Closed in #230

[Dsantra92]

I implemented caching in #230 but this doesn't take away the fact that docs generation will be slow if you are rendering pluto notebooks. Currently, PlutoStaticHTML allows us to use cache if the source file has the same SHA and was rendered with the same Julia version. So if you are using Julia 1.7.1 and the cache files were rendered with Julia 1.8.2, the cache is discarded. The rendering of new notebooks is inevitable if you are contributing notebooks.

Pluto with a cache mechanism comes with a downside. The maintainer is required to make sure that there are no open ends to the notebook. For instance, rendering with local data is not reproducible.

Time to first doc can be annoying for people who are trying to contribute to the other docs. We can add an environment variable to control if the notebook is rendered or not.