Speeding up the docs build

[jpfairbanks]

@GeorgeR227, now that we have the overhaul in #231, what is the plan for the literate examples? Are there any that need to be worked into the current docs build?

One benefit of using Literate is that we can accelerate the docs with slurm, by launching jobs for each literate page and then including them in the final docs.

Another option is to have a script that runs simulations to generate the figures and then write docs pages that include those figures as references. Then the docs pages don't have to run the code that generates the figures in the docs build. That would let us use a standard pipeline for building the docs on github actions, but a buildkite job that can launch a slurm job for each page to build the figures by simulation on hipergator.

[jpfairbanks]

Ref: #218/#190

[GeorgeR227]

To be honest I haven't looked at Literate a lot but it seems to me like it's meant to speed up turning examples into markdown which can then be feed into Documenter which in turn creates the HTML doc pages. So from what I see, using Literate won't actually speed up the build but maybe speed up our workflow of turning physics into docs.

For our large simulations, like Navier-Stokes or NHS, setting up that pipeline sounds good, especially since those already have julia and slurm scripts ready.

A large time sink right now is also the package pre-compilation which takes around 8 minutes so tackling that would also help a lot.

[GeorgeR227]

Also, @lukem12345 and I were discussing yesterday that we should move in the Brusselator, and maybe Gray-Scott as well, example into a doc page.

[lukem12345]

Another option is to have a script that runs simulations to generate the figures and then write docs pages that include those figures as references. Then the docs pages don't have to run the code that generates the figures in the docs build. That would let us use a standard pipeline for building the docs on github actions, but a buildkite job that can launch a slurm job for each page to build the figures by simulation on hipergator.

I am worried that this would exacerbate issues related to keeping simulations (including the initial conditions and such) living in multiple locations in synch.

[jpfairbanks]

Given that Literate does not actually execute the docs pages in separate environments, but just generates the markdown for Documenter, I think that parallelizing that isn't actually helpful.

For our large simulations, like Navier-Stokes or NHS, setting up that pipeline sounds good, especially since those already have julia and slurm scripts ready.

We also want to accelerate as many of these sims with CUDA as possible, so having the docs build on the cluster and deposit the files for Documenter to load would be great.

Buildkite has a mechanism for building and deploying artifacts https://buildkite.com/docs/pipelines/artifacts. We could have all the simulation results build as an artifact and then have the documentation link to files in that artifact.

https://github.com/JuliaComputing/MultiDocumenter.jl/ has tools for aggregating docs from multiple packages into a single website. It can do link rewriting, so maybe we could use that to have docs that get images and results from a BK artifact.

[jpfairbanks]

Apparently execute=true on Literate.markdown will store the results so that Documenter doesn't have to rerun the cells when building the docs. https://github.com/JuliaDocs/Documenter.jl/issues/2456#issuecomment-1954469264