Include docs PDF in release assets

[visr]

Currently we only use the Quarto HTML output which we host online. For offline use it would be good to build and include the PDF output of our documentation.

https://quarto.org/docs/output-formats/pdf-basics.html

• get PDF output working, I believe https://github.com/Deltares/iMOD-Documentation already has it
• add it to CI for our nightly and release builds
• update the release process docs

Having this would alleviate #665, giving users a way to read old documentation.

[Hofer-Julian]

Sounds like a good idea. We should also check at least from time to time if the pdf is indeed complete and formatted nicely.

Having this would alleviate #665, giving users a way to read old documentation.

Agreed, a PDF is a nice alternative to hacking in a version selector or adding our own HTML page that links to the different versions (see e.g. GTK4 Rust docs)

[visr]

I tried adding a quarto-render-pdf task in pixi.toml, which is the same as quarto-render but with --to pdf.

First it complained that no TeX installation was detected, so I ran quarto install tinytex. After that it the amsmath package failed on some equations on allocations.qmd: "Package amsmath Error: Erroneous nesting of equation structures;"

[visr]

With #735 and #737 we are closer to PDF output. However, there is a bug that is fixed upstream in Quarto for including remote images, that was discussed in #737.

It's easiest to put this on hold until Quarto 1.4 is released, that is already available as a pre-release, but not in conda-forge / pixi.

[visr]

With the update to Quarto 1.4 in #1139 this is no longer Paused.

[Hofer-Julian]

This is currently blocked by conda-forge/quarto-feedstock#44

[visr]

This is currently blocked by #1298 (comment)