Build docs as a PDF

[odow]

Preview: https://jump.dev/JuMP.jl/previews/PR2760/JuMP.pdf

Closes #1881

Needs

• Fix text/latex MIME type in LaTeXWriter JuliaDocs/Documenter.jl#1709

[codecov]

Codecov Report

Merging #2760 (c82707d) into master (876258c) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #2760   +/-   ##
=======================================
  Coverage   94.25%   94.25%           
=======================================
  Files          43       43           
  Lines        5522     5522           
=======================================
  Hits         5205     5205           
  Misses        317      317           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 876258c...c82707d. Read the comment docs.

[mlubin]

Wow, that's a long pdf. We can change the authors on the first page to something like "The JuMP core developers and contributors".

[odow]

Yeah there's a few things I'd like to fix:

• Authorship
• Logo. Upstream issue: Some suggestions for the pdf manual first page JuliaDocs/Documenter.jl#949
• Some tables are too wide

• Better organize ordering of tutorials
• Numbering of chapters/sections is a bit weird in places Known issue: Level 2 headings become Chapters in pdf build if pages contains arrays of files JuliaDocs/Documenter.jl#1416. Trickier to get right than it seems.

[odow]

Still some problems building the LaTeX:

• LaTeX error around NormSpectralCone https://github.com/jump-dev/MathOptInterface.jl/blob/master/docs/src/manual/standard_form.md#matrix-cones

• Portfolio example

• Space shuttle

[odow]

Finally we have success: https://jump.dev/JuMP.jl/previews/PR2760/JuMP.pdf

Since things are building, this isn't blocking for JuMP 0.22. It can wait until we release a new version of MOI. I also need to tidy up the fact that each page should have a level-1 heading for the chapter (e.g., index.md doesn't), and there are a couple of broken links to sort.

The bigger issue is that the doc run is now 30 minutes! We may want to consider only enabling this before each release, rather than on every PR.

[odow]

Here's the upstream issue for tables: JuliaDocs/Documenter.jl#1205

[odow]

Currently blocked by #2780

[odow]

Here's the current build:

https://jump.dev/JuMP.jl/previews/PR2760/JuMP.pdf

So the time breakdown is:

• Install Julia: 280 seconds
• Literate examples: 300 seconds
• Build HTML: 265 seconds
• Build LaTeX: 835 seconds

So the LaTeX is a pretty sizable hit. Splitting the jobs into a parallel HTML and PDF build steps wouldn't help us very much. It's save a couple of minutes, but it'd complicate the PDF deployment. It's nice having everything in a single build step.

Overall, I'd suggest we merge this and see if we get annoyed by the 30 minute doc build. I can see that if we don't run the LaTeX build every time, we're quickly going to end up where the LaTeX doesn't build and we have to spend a lot of time debugging it before each release.

Having an up-to-date preview PDF is also quite useful for editing.

[odow]

Merging this until I get annoyed by it.