Build docs as a PDF

docs/.gitignore

@@ -1,4 +1,5 @@
 build/
+latex_build/
 src/examples/*.md
 src/examples/*/*.md
 src/tutorials/*/*.md

docs/make.jl

@@ -13,12 +13,26 @@ const _FAST = findfirst(isequal("--fast"), ARGS) !== nothing
 # Pass --fix to run with `doctests=:fix`.
 const _FIX = findfirst(isequal("--fix"), ARGS) !== nothing
 
+# 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
+
 # ==============================================================================
 #  Run literate.jl
 # ==============================================================================
 
 function _link_example(content)
     edit_url = match(r"EditURL = \"(.+?)\"", content)[1]
+    if !_IS_GITHUB_ACTIONS
+        # The link won't work locally. So hard-code in a URL.
+        edit_url = replace(
+            edit_url,
+            "<unknown>" =>
+                "https://github.com/jump-dev/JuMP.jl/tree/master",
+        )
+    end
     return content *
            "---\n\n!!! tip\n    This tutorial was generated using [Literate.jl](https://github.com/fredrikekre/Literate.jl). [View the source `.jl` file on GitHub]($(edit_url)).\n"
 end
@@ -74,6 +88,10 @@ end
 # This constant dictates the layout of the documentation. It is manually
 # constructed so that we can have control over the order in which pages are
 # shown. If you add a new page to the documentation, make sure to add it here!
+#
+# !!! warning
+#     If you move any of the top-level chapters around, make sure to update the
+#     index of the "release_notes.md" in the section which builds the PDF.
 const _PAGES = [
     "Introduction" => ["index.md", "installation.md"],
     "Tutorials" => [
@@ -154,7 +172,7 @@ const _PAGES = [
         "reference/callbacks.md",
         "reference/extensions.md",
     ],
-    "Background information" => [
+    "Background Information" => [
         "background/should_i_use.md",
         "background/algebraic_modeling_languages.md",
     ],
@@ -248,10 +266,10 @@ end
 _validate_pages()
 
 # ==============================================================================
-#  Build and deploy
+#  Build the HTML docs
 # ==============================================================================
 
-Documenter.makedocs(
+@time Documenter.makedocs(
     sitename = "JuMP",
     authors = "The JuMP core developers and contributors",
     format = Documenter.HTML(
@@ -262,7 +280,6 @@ Documenter.makedocs(
         assets = ["assets/extra_styles.css"],
         sidebar_sitename = false,
     ),
-    # `strict = true` causes Documenter to throw an error if the Doctests fail.
     strict = true,
     # ==========================================================================
     # `modules = [JuMP]`, along with `checkdocs = :exports` causes Documenter to
@@ -284,6 +301,36 @@ Documenter.makedocs(
     pages = _PAGES,
 )
 
+# ==============================================================================
+#  Build the LaTeX docs (if needed)
+# ==============================================================================
+
+if _PDF
+    # Small inconsistency between HTML and LaTeX! We want the release notes to
+    # be a separate chapter in LaTeX, but we don't want an annoying drop-down in
+    # HTML.
+    _PAGES[7] = "Release Notes" => ["release_notes.md"]
+    latex_platform = _IS_GITHUB_ACTIONS ? "docker" : "native"
+    @time Documenter.makedocs(
+        sitename = "JuMP",
+        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", "JuMP.pdf"),
+        joinpath(@__DIR__, "build", "JuMP.pdf"),
+    )
+end
+
+# ==============================================================================
+#  Deploy everything in `build`
+# ==============================================================================
+
 Documenter.deploydocs(
     repo = "github.com/jump-dev/JuMP.jl.git",
     push_preview = true,

docs/src/background/algebraic_modeling_languages.md

@@ -171,7 +171,7 @@ There are three main parts to MathOptInterface:
  1. A solver-independent API that abstracts concepts such as adding and deleting
     variables and constraints, setting and getting parameters, and querying
     results. For more information on the MathOptInterface API, read the
-    [documentation](@ref moi_documentation)
+    [documentation](@ref moi_documentation).
 
  2. An automatic rewriting system based on equivalent formulations of a
     constraint. For more information on this rewriting system, read the

docs/src/tutorials/nonlinear/space_shuttle_reentry_trajectory.jl

@@ -104,7 +104,7 @@
 # which is equivalent to maximizing the final latitude of the vehicle,
 # i.e., $J = \theta(t_F)$.
 
-# ![Max crossrange shuttle reentry](../../../assets/space_shuttle.png)
+# ![Max crossrange shuttle reentry](../../assets/space_shuttle.png)
 
 # ### Approach
 # We will use a discretized model of time, with a fixed number of discretized points, $n$.