Build docs as a PDF

.gitignore

@@ -3,6 +3,7 @@
 *.jl.mem
 .vscode/*
 docs/build/
+docs/latex_build/
 docs/site/
 test/Benchmarks/*.json
 Manifest.toml

docs/Project.toml

@@ -5,6 +5,6 @@ JSONSchema = "7d188eb4-7ad8-530c-ae41-71a32a6d4692"
 MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee"
 
 [compat]
-Documenter = "0.27"
+Documenter = "0.27.9"
 JSON = "0.21"
 JSONSchema = "0.3"

docs/make.jl

@@ -1,12 +1,85 @@
-using Documenter, MathOptInterface
+import Documenter
+import MathOptInterface
 
-"""
-Pass `julia docs/make.jl --fix` to rebuild the doctests.
-"""
+# Pass --fix` to rebuild the doctests.
 const _FIX = findfirst(isequal("--fix"), ARGS) !== nothing
 
-makedocs(
+# A flag to check if we are running in a GitHub action.
+const _IS_GITHUB_ACTIONS = get(ENV, "GITHUB_ACTIONS", "false") == "true"
+
+# Pass --pdf to build the PDF. On GitHub actions, we always build the PDF.
+const _PDF = findfirst(isequal("--pdf"), ARGS) !== nothing || _IS_GITHUB_ACTIONS
+
+# ==============================================================================
+#  Documentation structure
+# ==============================================================================
+
+const _PAGES = [
+    "Introduction" => "index.md",
+    "Background" => [
+        "background/motivation.md",
+        "background/duality.md",
+        "background/naming_conventions.md",
+    ],
+    "Tutorials" => [
+        "tutorials/example.md",
+        "tutorials/implementing.md",
+        "tutorials/mathprogbase.md",
+        "tutorials/bridging_constraint.md",
+        "tutorials/manipulating_expressions.md",
+        "tutorials/latency.md",
+    ],
+    "Manual" => [
+        "manual/standard_form.md",
+        "manual/models.md",
+        "manual/variables.md",
+        "manual/constraints.md",
+        "manual/solutions.md",
+        "manual/modification.md",
+    ],
+    "API Reference" => [
+        "reference/standard_form.md",
+        "reference/models.md",
+        "reference/variables.md",
+        "reference/constraints.md",
+        "reference/modification.md",
+        "reference/nonlinear.md",
+        "reference/callbacks.md",
+        "reference/errors.md",
+    ],
+    "Submodules" => [
+        "Benchmarks" => [
+            "Overview" => "submodules/Benchmarks/overview.md",
+            "API Reference" => "submodules/Benchmarks/reference.md",
+        ],
+        "Bridges" => [
+            "Overview" => "submodules/Bridges/overview.md",
+            "Implementation" => "submodules/Bridges/implementation.md",
+            "API Reference" => "submodules/Bridges/reference.md",
+        ],
+        "FileFormats" => [
+            "Overview" => "submodules/FileFormats/overview.md",
+            "API Reference" => "submodules/FileFormats/reference.md",
+        ],
+        "Utilities" => [
+            "Overview" => "submodules/Utilities/overview.md",
+            "API Reference" => "submodules/Utilities/reference.md",
+        ],
+        "Test" => [
+            "Overview" => "submodules/Test/overview.md",
+            "API Reference" => "submodules/Test/reference.md",
+        ],
+    ],
+    "Release notes" => "release_notes.md",
+]
+
+# ==============================================================================
+#  Build the HTML docs
+# ==============================================================================
+
+@time Documenter.makedocs(
     sitename = "MathOptInterface",
+    authors = "The JuMP core developers and contributors",
     format = Documenter.HTML(
         # See https://github.com/JuliaDocs/Documenter.jl/issues/868
         prettyurls = get(ENV, "CI", nothing) == "true",
@@ -17,67 +90,36 @@ makedocs(
     modules = [MathOptInterface],
     checkdocs = :exports,
     doctest = _FIX ? :fix : true,
-    pages = [
-        "Introduction" => "index.md",
-        "Background" => [
-            "background/motivation.md",
-            "background/duality.md",
-            "background/naming_conventions.md",
-        ],
-        "Tutorials" => [
-            "tutorials/example.md",
-            "tutorials/implementing.md",
-            "tutorials/mathprogbase.md",
-            "tutorials/bridging_constraint.md",
-            "tutorials/manipulating_expressions.md",
-            "tutorials/latency.md",
-        ],
-        "Manual" => [
-            "manual/standard_form.md",
-            "manual/models.md",
-            "manual/variables.md",
-            "manual/constraints.md",
-            "manual/solutions.md",
-            "manual/modification.md",
-        ],
-        "API Reference" => [
-            "reference/standard_form.md",
-            "reference/models.md",
-            "reference/variables.md",
-            "reference/constraints.md",
-            "reference/modification.md",
-            "reference/nonlinear.md",
-            "reference/callbacks.md",
-            "reference/errors.md",
-        ],
-        "Submodules" => [
-            "Benchmarks" => [
-                "Overview" => "submodules/Benchmarks/overview.md",
-                "API Reference" => "submodules/Benchmarks/reference.md",
-            ],
-            "Bridges" => [
-                "Overview" => "submodules/Bridges/overview.md",
-                "Implementation" => "submodules/Bridges/implementation.md",
-                "API Reference" => "submodules/Bridges/reference.md",
-            ],
-            "FileFormats" => [
-                "Overview" => "submodules/FileFormats/overview.md",
-                "API Reference" => "submodules/FileFormats/reference.md",
-            ],
-            "Utilities" => [
-                "Overview" => "submodules/Utilities/overview.md",
-                "API Reference" => "submodules/Utilities/reference.md",
-            ],
-            "Test" => [
-                "Overview" => "submodules/Test/overview.md",
-                "API Reference" => "submodules/Test/reference.md",
-            ],
-        ],
-        "Release notes" => "release_notes.md",
-    ],
+    pages = _PAGES,
 )
 
-deploydocs(
-    push_preview = true,
+# ==============================================================================
+#  Build the LaTeX docs (if needed)
+# ==============================================================================
+
+if _PDF
+    latex_platform = _IS_GITHUB_ACTIONS ? "docker" : "native"
+    @time Documenter.makedocs(
+        sitename = "MathOptInterface",
+        authors = "The JuMP core developers and contributors",
+        format = Documenter.LaTeX(platform = latex_platform),
+        build = "latex_build",
+        pages = _PAGES,
+    )
+    # Hack for deploying: copy the pdf (and only the PDF) into the HTML build
+    # directory! We don't want to copy everything in `latex_build` because it
+    # includes lots of extraneous LaTeX files.
+    cp(
+        joinpath(@__DIR__, "latex_build", "MathOptInterface.pdf"),
+        joinpath(@__DIR__, "build", "MathOptInterface.pdf"),
+    )
+end
+
+# ==============================================================================
+#  Deploy everything in `build`
+# ==============================================================================
+
+Documenter.deploydocs(
     repo = "github.com/jump-dev/MathOptInterface.jl.git",
+    push_preview = true,
 )

docs/src/index.md

@@ -1,12 +1,10 @@
-!!! warning
-    This documentation is still under construction. If you need help with JuMP,
-    read the [JuMP documentation](https://jump.dev/JuMP.jl/stable/) instead. If
-    you are writing a solver interface and need help with MOI, join the
-    [developer chatroom](https://gitter.im/JuliaOpt/JuMP-dev) and ask away!
+# Introduction
 
-# MathOptInterface
+!!! note
+    This documentation is also available in PDF format:
+    [MathOptInterface.pdf](MathOptInterface.pdf).
 
-# What is MathOptInterface?
+## What is MathOptInterface?
 
 [MathOptInterface.jl](https://github.com/jump-dev/MathOptInterface.jl) (MOI) is
 an abstraction layer designed to provide a unified interface to mathematical

docs/src/manual/standard_form.md

@@ -72,16 +72,16 @@ The one-dimensional set types implemented in MathOptInterface.jl are:
 The vector-valued set types implemented in MathOptInterface.jl are:
 
 * [`Reals(dimension)`](@ref MathOptInterface.Reals):
-  ``\mathbb{R}^\mbox{dimension}``
-* [`Zeros(dimension)`](@ref MathOptInterface.Zeros): ``0^\mbox{dimension}``
+  ``\mathbb{R}^{\mbox{dimension}}``
+* [`Zeros(dimension)`](@ref MathOptInterface.Zeros): ``0^{\mbox{dimension}}``
 * [`Nonnegatives(dimension)`](@ref MathOptInterface.Nonnegatives):
-  ``\{ x \in \mathbb{R}^\mbox{dimension} : x \ge 0 \}``
+  ``\{ x \in \mathbb{R}^{\mbox{dimension}} : x \ge 0 \}``
 * [`Nonpositives(dimension)`](@ref MathOptInterface.Nonpositives):
-  ``\{ x \in \mathbb{R}^\mbox{dimension} : x \le 0 \}``
+  ``\{ x \in \mathbb{R}^{\mbox{dimension}} : x \le 0 \}``
 * [`SecondOrderCone(dimension)`](@ref MathOptInterface.SecondOrderCone):
-  ``\{ (t,x) \in \mathbb{R}^\mbox{dimension} : t \ge \lVert x \rVert_2 \}``
+  ``\{ (t,x) \in \mathbb{R}^{\mbox{dimension}} : t \ge \lVert x \rVert_2 \}``
 * [`RotatedSecondOrderCone(dimension)`](@ref MathOptInterface.RotatedSecondOrderCone):
-  ``\{ (t,u,x) \in \mathbb{R}^\mbox{dimension} : 2tu \ge \lVert x \rVert_2^2, t,u \ge 0 \}``
+  ``\{ (t,u,x) \in \mathbb{R}^{\mbox{dimension}} : 2tu \ge \lVert x \rVert_2^2, t,u \ge 0 \}``
 * [`ExponentialCone()`](@ref MathOptInterface.ExponentialCone):
   ``\{ (x,y,z) \in \mathbb{R}^3 : y \exp (x/y) \le z, y > 0 \}``
 * [`DualExponentialCone()`](@ref MathOptInterface.DualExponentialCone):
@@ -90,14 +90,14 @@ The vector-valued set types implemented in MathOptInterface.jl are:
   ``\{ (t,x) \in \mathbb{R}^{n+1} : x \ge 0, t \le \sqrt[n]{x_1 x_2 \cdots x_n} \}``
   where ``n`` is ``\mbox{dimension} - 1``
 * [`PowerCone(exponent)`](@ref MathOptInterface.PowerCone):
-  ``\{ (x,y,z) \in \mathbb{R}^3 : x^\mbox{exponent} y^{1-\mbox{exponent}} \ge |z|, x,y \ge 0 \}``
+  ``\{ (x,y,z) \in \mathbb{R}^3 : x^{\mbox{exponent}} y^{1-\mbox{exponent}} \ge |z|, x,y \ge 0 \}``
 * [`DualPowerCone(exponent)`](@ref MathOptInterface.DualPowerCone):
-  ``\{ (u,v,w) \in \mathbb{R}^3 : \frac{u}{\mbox{exponent}}^\mbox{exponent}\frac{v}{1-\mbox{exponent}}^{1-\mbox{exponent}} \ge |w|, u,v \ge 0 \}``
-* [`NormOneCone(dimension)`](@ref MathOptInterface.NormOneCone): ``\{ (t,x) \in \mathbb{R}^\mbox{dimension} : t \ge \lVert x \rVert_1 \}`` where ``\lVert x \rVert_1 = \sum_i \lvert x_i \rvert``
+  ``\{ (u,v,w) \in \mathbb{R}^3 : \frac{u}{\mbox{exponent}}^{\mbox{exponent}}\frac{v}{1-\mbox{exponent}}^{1-\mbox{exponent}} \ge |w|, u,v \ge 0 \}``
+* [`NormOneCone(dimension)`](@ref MathOptInterface.NormOneCone): ``\{ (t,x) \in \mathbb{R}^{\mbox{dimension}} : t \ge \lVert x \rVert_1 \}`` where ``\lVert x \rVert_1 = \sum_i \lvert x_i \rvert``
 * [`NormInfinityCone(dimension)`](@ref MathOptInterface.NormInfinityCone):
-  ``\{ (t,x) \in \mathbb{R}^\mbox{dimension} : t \ge \lVert x \rVert_\infty \}`` where ``\lVert x \rVert_\infty = \max_i \lvert x_i \rvert``.
+  ``\{ (t,x) \in \mathbb{R}^{\mbox{dimension}} : t \ge \lVert x \rVert_\infty \}`` where ``\lVert x \rVert_\infty = \max_i \lvert x_i \rvert``.
 * [`RelativeEntropyCone(dimension)`](@ref MathOptInterface.RelativeEntropyCone):
-  ``\{ (u, v, w) \in \mathbb{R}^\mbox{dimension} : u \ge \sum_i w_i \log (\frac{w_i}{v_i}), v_i \ge 0, w_i \ge 0 \}``
+  ``\{ (u, v, w) \in \mathbb{R}^{\mbox{dimension}} : u \ge \sum_i w_i \log (\frac{w_i}{v_i}), v_i \ge 0, w_i \ge 0 \}``
 
 ## Matrix cones
 
@@ -119,9 +119,9 @@ The matrix-valued set types implemented in MathOptInterface.jl are:
   ``\{ (t,u,X) \in \mathbb{R}^{2+\mbox{dimension}^2} : t \le u \log(\det(X/u)), X \mbox{ is a PSD matrix}, u > 0 \}``
 
 * [`NormSpectralCone(row_dim, column_dim)`](@ref MathOptInterface.NormSpectralCone):
-  ``\{ (t, X) \in \mathbb{R}^{1 + \mbox{row_dim} \times \mbox{column_dim}} : t \ge \sigma_1(X), X \mbox{ is a matrix with row_dim rows and column_dim columns} \}``
+  ``\{ (t, X) \in \mathbb{R}^{1 + \mbox{row\_dim} \times \mbox{column\_dim}} : t \ge \sigma_1(X), X \mbox{ is a matrix with row\_dim rows and column\_dim columns} \}``
 * [`NormNuclearCone(row_dim, column_dim)`](@ref MathOptInterface.NormNuclearCone):
-  ``\{ (t, X) \in \mathbb{R}^{1 + \mbox{row_dim} \times \mbox{column_dim}} : t \ge \sum_i \sigma_i(X), X \mbox{ is a matrix with row_dim rows and column_dim columns} \}``
+  ``\{ (t, X) \in \mathbb{R}^{1 + \mbox{row\_dim} \times \mbox{column\_dim}} : t \ge \sum_i \sigma_i(X), X \mbox{ is a matrix with row\_dim rows and column\_dim columns} \}``
 
 Some of these cones can take two forms: `XXXConeTriangle` and `XXXConeSquare`.
 

docs/src/tutorials/latency.md

@@ -264,7 +264,7 @@ ProfileView.view(flamegraph(tinf))
 ```
 
 Here's how things looked in mid-August 2021:
-![flamegraph](https://user-images.githubusercontent.com/8177701/129137091-fb78c4a0-2208-4418-968f-24ff15370351.png)
+![flamegraph](../assets/latency.png)
 
 There are a few opportunities for improvement (non-red flames, particularly on
 the right). But the main problem is a large red (non-precompilable due to method