diff --git a/.gitignore b/.gitignore index fe01be8354..4b1315acc8 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,7 @@ *.jl.mem .vscode/* docs/build/ +docs/latex_build/ docs/site/ test/Benchmarks/*.json Manifest.toml diff --git a/docs/Project.toml b/docs/Project.toml index 084be214a2..894c17310b 100644 --- a/docs/Project.toml +++ b/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" diff --git a/docs/make.jl b/docs/make.jl index 93d3030079..6aab1f9764 100644 --- a/docs/make.jl +++ b/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, ) diff --git a/docs/src/assets/latency.png b/docs/src/assets/latency.png new file mode 100644 index 0000000000..9b51f3b25f Binary files /dev/null and b/docs/src/assets/latency.png differ diff --git a/docs/src/index.md b/docs/src/index.md index dd010f5dc6..73937f886a 100644 --- a/docs/src/index.md +++ b/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 diff --git a/docs/src/manual/standard_form.md b/docs/src/manual/standard_form.md index bc5a4f094d..7b23e1e0f2 100644 --- a/docs/src/manual/standard_form.md +++ b/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`. diff --git a/docs/src/tutorials/latency.md b/docs/src/tutorials/latency.md index b46de1aaeb..1279a52b9b 100644 --- a/docs/src/tutorials/latency.md +++ b/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