update to Documenter v1 (#657)

* update to Documenter v1

* fix

* try to appease vale

* Update docs/make.jl

---------

Co-authored-by: Oscar Dowson <odow@users.noreply.github.com>

Author: ericphanson

docs/Project.toml

@@ -23,7 +23,7 @@ Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 [compat]
 DataFrames = "1"
 Distributions = "0.25"
-Documenter = "0.27"
+Documenter = "1"
 Dualization = "0.5.8"
 ECOS = "1"
 GLPK = "1"

docs/make.jl

@@ -30,6 +30,9 @@ function _literate_directory(dir)
         # `include` the file to test it before `#src` lines are removed. It is
         # in a testset to isolate local variables between files.
         Test.@testset "$(filename)" begin
+            # we can't use just `mod = Module()`
+            # as some examples use `include`.
+            # TODO- remove `include`'s from examples
             mod = @eval module $(gensym()) end
             Base.include(mod, filename)
         end
@@ -84,20 +87,19 @@ open(joinpath(@__DIR__, "src", "changelog.md"), "r") do in_io
 end
 
 # ==============================================================================
-#  Build annd release
+#  Build and release
 # ==============================================================================
 
 Documenter.makedocs(
     sitename = "Convex.jl",
-    repo = "https://github.com/jump-dev/Convex.jl/blob/{commit}{path}#L{line}",
     # TODO(odow): uncomment this once all docstrings are in the manual
     # modules = [Convex],
     format = Documenter.HTML(;
         ansicolor = true,
         collapselevel = 1,
         prettyurls = get(ENV, "CI", nothing) == "true",
     ),
-    strict = true,
+    warnonly = [:cross_references],
     pages = [
         "Introduction" => [
             "Home" => "index.md",

docs/src/examples/general_examples/basic_usage.jl

@@ -6,7 +6,7 @@ using SCS
 
 # ### Linear program
 #
-# $$
+# ```math
 # \begin{array}{ll}
 #   \text{maximize} & c^T x \\
 #   \text{subject to} & A x \leq b\\
@@ -15,7 +15,7 @@ using SCS
 #   & x_2 \leq 5 \\
 #   & x_1 + x_4 - x_2 \leq 10 \\
 # \end{array}
-# $$
+# ```
 #
 
 x = Variable(4)
@@ -33,15 +33,15 @@ println(evaluate(x[1] + x[4] - x[2]))
 
 # ### Matrix Variables and promotions
 #
-# $$
+# ```math
 # \begin{array}{ll}
 #   \text{minimize} & \| X \|_F + y \\
 #   \text{subject to} & 2 X \leq 1\\
 #   & X' + y \geq 1 \\
 #   & X \geq 0 \\
 #   & y \geq 0 \\
 # \end{array}
-# $$
+# ```
 #
 
 X = Variable(2, 2)
@@ -55,14 +55,14 @@ p.optval
 
 # ### Norm, exponential and geometric mean
 #
-# $$
+# ```math
 # \begin{array}{ll}
 #   \text{satisfy} & \| x \|_2 \leq 100 \\
 #   & e^{x_1} \leq 5 \\
 #   & x_2 \geq 7 \\
 #   & \sqrt{x_3 x_4} \geq x_2
 # \end{array}
-# $$
+# ```
 #
 
 x = Variable(4)

docs/src/examples/general_examples/control.jl

@@ -7,9 +7,9 @@
 # denotes the input into the system over time. Linear constraints are used to
 # capture the evolution of the system over time:
 #
-# $$
+# ```math
 # x(t) = Ax(t - 1) + Bu(t), \ \text{for} \ t = 1,\ldots, T,
-# $$
+# ```
 #
 # where the numerical matrices $A$ and $B$ are called the dynamics and input matrices,
 # respectively.
@@ -30,7 +30,9 @@
 # have physical meaning, so we often want to find a sequence inputs that also
 # minimizes a least squares objective like the following:
 #
-# $$\sum_{t = 0}^T \|Fx(t)\|^2_2 + \sum_{t = 1}^T\|Gu(t)\|^2_2,$$
+# ```math
+# \sum_{t = 0}^T \|Fx(t)\|^2_2 + \sum_{t = 1}^T\|Gu(t)\|^2_2,
+# ```
 #
 # where $F$ and $G$ are numerical matrices.
 #
@@ -42,12 +44,12 @@
 # By the basic laws of physics, the relationship between force, velocity, and position
 # must satisfy:
 #
-# $$
+# ```math
 #   \begin{aligned}
 #     p(t+1) &= p(t) + h v(t) \\
 #     v(t+1) &= v(t) + h a(t)
 #   \end{aligned}.
-# $$
+# ```
 #
 # Here, $a(t)$ denotes the acceleration at time $t$, for which we use
 # $a(t) = f(t) / m + g - d v(t)$,
@@ -56,20 +58,20 @@
 #
 # Additionally, we have our initial/final position/velocity conditions:
 #
-# $$
+# ```math
 #   \begin{aligned}
 #     p(1) &= p_i\\
 #     v(1) &= v_i\\
 #     p(T+1) &= p_f\\
 #     v(T+1) &= 0
 #   \end{aligned}
-# $$
+# ```
 #
 # One reasonable objective to minimize would be
 #
-# $$
+# ```math
 #   \text{objective} = \mu \sum_{t = 1}^{T+1} (v(t))^2 + \sum_{t = 1}^T (f(t))^2
-# $$
+# ```
 #
 # We would like to keep both the forces small to perhaps save fuel, and keep
 # the velocities small for safety concerns.

docs/src/examples/mixed_integer/binary_knapsack.jl

@@ -3,13 +3,13 @@
 #
 # This can be formulated as a mixed-integer program as:
 #
-# $$
+# ```math
 # \begin{array}{ll}
 #   \text{maximize} & x' p \\
 #     \text{subject to} & x \in \{0, 1\} \\
 #   & w' x \leq C \\
 # \end{array}
-# $$
+# ```
 #
 # where $x$ is a vector is size $n$ where $x_i$ is one if we chose to keep the object in the knapsack, 0 otherwise.
 

docs/src/examples/optimization_with_complex_variables/Fidelity in Quantum Information Theory.jl

@@ -3,20 +3,20 @@
 #
 # The Fidelity between two Hermitian semidefinite matrices P and Q is defined as:
 #
-# $$
+# ```math
 # F(P, Q) = \|P^{1/2}Q^{1/2}\|_{\text{tr}} = \max_U \mathrm{tr}(P^{1/2}U Q^{1/2})
-# $$
+# ```
 #
 # where the trace norm $\|\cdot\|_{\text{tr}}$ is the sum of the singular values, and the maximization goes over the set of all unitary matrices U. This quantity can be expressed as the optimal value of the following complex-valued SDP:
 #
-# $$
+# ```math
 # \begin{array}{ll}
 #   \text{maximize} &  \frac{1}{2}\text{tr}(Z+Z^\dagger) \\
 #   \text{subject to} &\\
 #   & \left[\begin{array}{cc}P&Z\\{Z}^{\dagger}&Q\end{array}\right] \succeq 0\\
 #   & Z \in \mathbf {C}^{n \times n}\\
 # \end{array}
-# $$
+# ```
 #
 
 using Convex, SCS, LinearAlgebra

docs/src/examples/optimization_with_complex_variables/phase_recovery_using_MaxCut.jl

@@ -16,12 +16,12 @@
 #
 # The original representation of the problem is as follows:
 #
-# $$
+# ```math
 # \begin{array}{ll}
 #   \text{find} & x \in \mathbb{C}^p \\
 #     \text{subject to} & |Ax| = b
 # \end{array}
-# $$
+# ```
 #
 # where $A \in \mathbb{C}^{n \times p}$ and $b \in \mathbb{R}^n$.
 
@@ -38,13 +38,13 @@
 # Define the positive semidefinite hermitian matrix
 # $M = \text{diag}(b) (I - A A^*) \text{diag}(b)$. The problem is:
 #
-# $$
+# ```math
 # \begin{array}{ll}
 #   \text{minimize} & \langle U, M \rangle \\
 #     \text{subject to} & \text{diag}(U) = 1\\
 #     & U \succeq 0
 # \end{array}
-# $$
+# ```
 #
 # Here the variable $U$ must be hermitian ($U \in \mathbb{H}_n $),
 # and we have a solution to the phase recovery problem if $U = u u^*$

docs/src/examples/optimization_with_complex_variables/povm_simulation.jl

@@ -1,7 +1,9 @@
 # # POVM simulation
 # This notebook shows how we can check how much depolarizing noise a qubit positive operator-valued measure (POVM) can take before it becomes simulable by projective measurements. The general method is described in [arXiv:1609.06139](https://arxiv.org/abs/1609.06139). The question of simulability by projective measurements boils down to an SDP problem. Eq. (8) from the paper defines the noisy POVM that we obtain subjecting a POVM $\mathbf{M}$ to a depolarizing channel $\Phi_t$:
 #
-# $$\left[\Phi_t\left(\mathbf{M}\right)\right]_i := t M_i + (1-t)\frac{\mathrm{tr}(M_i)}{d} \mathbb{1}.$$
+# ```math
+# \left[\Phi_t\left(\mathbf{M}\right)\right]_i := t M_i + (1-t)\frac{\mathrm{tr}(M_i)}{d} \mathbb{1}.
+# ```
 #
 # If this visibility $t\in[0,1]$ is one, the POVM $\mathbf{M}$ is simulable.
 #

docs/src/examples/supplemental_material/Convex.jl_intro_ISMP2015.jl

@@ -16,34 +16,34 @@
 # * [CVXPY](https://github.com/cvxgrp/cvxpy): Steven Diamond, Eric Chu, Stephen Boyd
 # * [JuliaOpt](https://github.com/JuliaOpt): Miles Lubin, Iain Dunning, Joey Huchette
 
-## initial package installation
+# initial package installation
 
 #-
 
-## Make the Convex.jl module available
+# Make the Convex.jl module available
 using Convex, SparseArrays, LinearAlgebra
 using SCS # first order splitting conic solver [O'Donoghue et al., 2014]
 
-## Generate random problem data
+# Generate random problem data
 m = 50;
 n = 100;
 A = randn(m, n)
 x♮ = sprand(n, 1, 0.5) # true (sparse nonnegative) parameter vector
 noise = 0.1 * randn(m)    # gaussian noise
 b = A * x♮ + noise      # noisy linear observations
 
-## Create a (column vector) variable of size n.
+# Create a (column vector) variable of size n.
 x = Variable(n)
 
-## nonnegative elastic net with regularization
+# nonnegative elastic net with regularization
 λ = 1
 μ = 1
 problem = minimize(
     square(norm(A * x - b)) + λ * square(norm(x)) + μ * norm(x, 1),
     x >= 0,
 )
 
-## Solve the problem by calling solve!
+# Solve the problem by calling `solve!`
 solve!(problem, SCS.Optimizer; silent_solver = true)
 
 println("problem status is ", problem.status) # :Optimal, :Infeasible, :Unbounded etc.
@@ -62,24 +62,25 @@ using Interact, Plots
     solve!(problem, SCS.Optimizer; silent_solver = true)
     histogram(evaluate(x), xlims = (0, 3.5), label = "x")
 end
+nothing # hide
 
 # # Quick convex prototyping
 
 #-
 
 # ## Variables
 
-## Scalar variable
+# Scalar variable
 x = Variable()
 
 #-
 
-## (Column) vector variable
+# (Column) vector variable
 y = Variable(4)
 
 #-
 
-## Matrix variable
+# Matrix variable
 Z = Variable(4, 4)
 
 # # Expressions
@@ -132,7 +133,7 @@ p = minimize(objective, constraint)
 
 #-
 
-## solve the problem
+# Solve the problem:
 solve!(p, SCS.Optimizer; silent_solver = true)
 p.status
 
@@ -142,7 +143,7 @@ evaluate(x)
 
 #-
 
-## can evaluate expressions directly
+# Can evaluate expressions directly:
 evaluate(objective)
 
 # ## Pass to solver
@@ -163,18 +164,18 @@ evaluate(objective)
 
 # ## Warmstart
 
-## Generate random problem data
+# Generate random problem data:
 m = 50;
 n = 100;
 A = randn(m, n)
 x♮ = sprand(n, 1, 0.5) # true (sparse nonnegative) parameter vector
 noise = 0.1 * randn(m)    # gaussian noise
 b = A * x♮ + noise      # noisy linear observations
 
-## Create a (column vector) variable of size n.
+# Create a (column vector) variable of size n.
 x = Variable(n)
 
-## nonnegative elastic net with regularization
+# nonnegative elastic net with regularization
 λ = 1
 μ = 1
 problem = minimize(
@@ -187,7 +188,7 @@ problem = minimize(
 
 # # DCP examples
 
-## affine
+# - affine
 x = Variable(4)
 y = Variable(2)
 sum(x) + y[2]
@@ -196,22 +197,14 @@ sum(x) + y[2]
 
 2 * maximum(x) + 4 * sum(y) - sqrt(y[1] + x[1]) - 7 * minimum(x[2:4])
 
-#-
-
-## not dcp compliant
+# - not DCP compliant
 log(x) + square(x)
 
-#-
-
-## $f$ is convex increasing and $g$ is convex
+# - Composition $f\circ g$ where $f$ is convex increasing and $g$ is convex
 square(pos(x))
 
-#-
-
-## $f$ is convex decreasing and $g$ is concave
+# - Composition $f\circ g$ where $f$ is convex decreasing and $g$ is concave
 invpos(sqrt(x))
 
-#-
-
-## $f$ is concave increasing and $g$ is concave
+# - Composition $f\circ g$ where $f$ is concave increasing and $g$ is concave
 sqrt(sqrt(x))