Faster documentation building by decoupling Literate.jl and Documenter.jl

[nathanaelbosch]

The documentation of DFTK.jl is largely written as .jl files which are then turned into markdown with Literate.jl. The markdown files are then used by Documenter.jl to build the actual documentation of DFTK.jl. But many of the examples are quite costly, so building the full documentation from scratch can take quite some time. One idea to improve the workflow would be to decouple "running the examples" from "building the documentation", such that we don't have to build the full documentation from scratch each time.

How: Literate.jl already provides options to include the outputs in the produced markdown file by setting execute=true, and we then also need to change the default code block formatting by changing the codefence:

        Literate.markdown(
            file.src, file.dest;
            flavor=Literate.DocumenterFlavor(),
            credit=false,
            preprocess=add_badges(badges),
            execute=true,
            codefence="````julia" => "````",
        )

The resulting files then don't contain any code for Documenter.jl to execute, so the actual Documenter.jl run is quite fast. When doing this, we should also not delete the .md files generated by Literate.jl.

Open questions:
There are some minor things that might still need to be fixed regarding styling (the codeblocks look a bit different but this can be fixed with a custom css) and badges (somehow they don't appear yet), but there are some open questions about how to set up the workflow:

• How to run examples: To be practically useful I think that we want some convenient way for deveopers to build some particular (or a set of) examples. The easiest way might be to extract all Literate.jl-related things from the current docs/make.jl into a docs/run_examples.jl, with some easy-to-use entry-point to run the code of some set of files.
• Where to store examples: We might not want to store examples on git to not inflate the history too much. Does this then mean that each developer will by default just have to run all the examples themselves at some point, to be able to build the full documentation? Also it might be quite tedious to define a good .gitignore rule for these files, as they are not confined to some single intermediate build location.
• When to enforce building the documentation: Do we want to optimize CI times or are we fine with the current ones? In the latter case, we could simply keep the current rules, but if CI improvements are a concern this needs more thought.

Next steps: I will open a PR to support all of this with some code and I'd be happy to get some feedback here or in the PR.

[mfherbst]

I would suggest to have a function in the make.jl file that uses the literate_files list to check which .md files need updating by literate (by checking modification times) and then only invokes literate on these. In combination with LiveServer this means that one is able to modify a .jl file, call this function and then the docs html would update automatically, which makes for a nice workflow.

[Technici4n]

Note: to make the docs build almost instantly, the following patch can be applied:

diff --git a/docs/make.jl b/docs/make.jl
index 1c3d34ca4..0ef97d0bb 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -195,9 +195,10 @@ for file in literate_files
     end
     Literate.markdown(file.src, file.dest;
                       flavor=Literate.DocumenterFlavor(),
-                      credit=false, preprocess=add_badges(badges))
-    Literate.notebook(file.src, file.dest; credit=false,
-                      execute=CONTINUOUS_INTEGRATION || DEBUG)
+                      credit=false, preprocess=add_badges(badges),
+                      config=Dict("edit_commit" => "master"))
+    # Literate.notebook(file.src, file.dest; credit=false,
+    #                   execute=CONTINUOUS_INTEGRATION || DEBUG)
 end
 
 # Generate the docs in BUILDPATH
@@ -232,6 +233,7 @@ makedocs(;
     pages=transform_to_md(PAGES),
     checkdocs=:exports,
     warnonly=DEBUG,
+    draft=true,
     remote_args...,
 )