[docs] add READMEs of supported solvers to the documentation

docs/.gitignore

@@ -6,3 +6,6 @@ src/tutorials/*/*.md
 src/moi/
 src/tutorials/linear/transp.txt
 src/release_notes.md
+src/packages/*.md
+!src/packages/solvers.md
+!src/packages/extensions.md

docs/Project.toml

@@ -2,6 +2,7 @@
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Downloads = "f43a241f-c20a-4ad4-852c-f6b1247861c6"
 GLPK = "60bf3e95-4087-53dc-ae20-288a0d20c6a6"
 HTTP = "cd3eb016-35fb-5094-929b-558a96fad6f3"
 HiGHS = "87dc4568-4c63-4d18-b0c0-bb2238e4078b"
@@ -19,6 +20,7 @@ Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 SCS = "c946c3f1-0d1f-5ce8-9dea-7daa1f7e2d13"
 SQLite = "0aa819cd-b072-5ff4-a722-6bc24af294d9"
 StatsPlots = "f3b207a7-027a-5e70-b257-86293d7955fd"
+TOML = "fa267f1f-6049-4f14-aa54-33bafae1ed76"
 Tables = "bd369af6-aec1-5ad0-b16a-f7cc5008161c"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 

docs/make.jl

@@ -1,8 +1,10 @@
 import Pkg
 Pkg.pkg"add Documenter#633a95a"
 import Documenter
+import Downloads
 import Literate
 import Test
+import TOML
 
 using JuMP
 const MathOptInterface = MOI
@@ -102,6 +104,57 @@ if !_FAST
     end
 end
 
+# ==============================================================================
+#  Add solver README
+# ==============================================================================
+
+const _LIST_OF_SOLVERS = Pair{String,String}[]
+const _LIST_OF_EXTENSIONS = Pair{String,String}[]
+for (solver, data) in TOML.parsefile(joinpath(@__DIR__, "packages.toml"))
+    user = get(data, "user", "jump-dev")
+    tag = data["rev"]
+    filename = get(data, "filename", "README.md")
+    out_filename = joinpath(@__DIR__, "src", "packages", "$solver.md")
+    Downloads.download(
+        "https://raw.githubusercontent.com/$user/$solver.jl/$tag/$filename",
+        out_filename,
+    )
+    if get(data, "has_html", false) == true
+        # Very simple detector of HTML to wrap in ```@raw html
+        lines = readlines(out_filename)
+        open(out_filename, "w") do io
+            closing_tag = nothing
+            for line in lines
+                tag = if startswith(line, "<img")
+                    "/>"
+                else
+                    m = match(r"\<([a-z0-9]+)", line)
+                    m === nothing ? nothing : "</$(m[1])>"
+                end
+                if closing_tag === nothing && tag !== nothing
+                    println(io, "```@raw html")
+                    closing_tag = tag
+                end
+                println(io, line)
+                if closing_tag !== nothing && endswith(line, closing_tag)
+                    println(io, "```")
+                    closing_tag = nothing
+                end
+            end
+        end
+    end
+    if get(data, "extension", false)
+        push!(_LIST_OF_EXTENSIONS, "$user/$solver.jl" => "packages/$solver.md")
+    else
+        push!(_LIST_OF_SOLVERS, "$user/$solver.jl" => "packages/$solver.md")
+    end
+end
+# Sort, with jump-dev repos at the start.
+sort!(_LIST_OF_SOLVERS; by = x -> (!startswith(x[1], "jump-dev/"), x[1]))
+sort!(_LIST_OF_EXTENSIONS; by = x -> (!startswith(x[1], "jump-dev/"), x[1]))
+pushfirst!(_LIST_OF_SOLVERS, "Introduction" => "packages/solvers.md")
+pushfirst!(_LIST_OF_EXTENSIONS, "Introduction" => "packages/extensions.md")
+
 # ==============================================================================
 #  JuMP documentation structure
 # ==============================================================================
@@ -214,7 +267,9 @@ const _PAGES = [
         "Style Guide" => "developers/style.md",
         "Roadmap" => "developers/roadmap.md",
     ],
-    "release_notes.md",
+    "Solvers" => _LIST_OF_SOLVERS,
+    "Extensions" => _LIST_OF_EXTENSIONS,
+    # "release_notes.md",  # To be added later
 ]
 
 # ==============================================================================
@@ -334,7 +389,7 @@ function _validate_pages()
     doc_src = joinpath(@__DIR__, "src", "")
     for (root, dir, files) in walkdir(doc_src)
         for file in files
-            if file == "changelog.md"
+            if file == "changelog.md" || file == "release_notes.md"
                 continue
             end
             filename = replace(joinpath(root, file), doc_src => "")
@@ -385,7 +440,7 @@ _validate_pages()
     # ==========================================================================
     # Skip doctests if --fast provided.
     doctest = _FIX ? :fix : !_FAST,
-    pages = _PAGES,
+    pages = vcat(_PAGES, "release_notes.md"),
 )
 
 # ==============================================================================
@@ -410,9 +465,11 @@ if _PDF
     for (root, dir, files) in walkdir(joinpath(@__DIR__, "src", "tutorials"))
         _remove_literate_footer.(joinpath.(root, dir))
     end
-    # Remove release notes from PDF
-    splice!(_PAGES, 7)   # JuMP release notes
-    pop!(_PAGES[end][2]) # MOI release notes
+    moi = pop!(_PAGES)   # remove /MathOptInterface
+    pop!(moi[2])        # remove /MathOptInterface/release_notes.md
+    pop!(_PAGES)        # remove /Extensions
+    pop!(_PAGES)        # remove /Solvers
+    push!(_PAGES, moi)  # Re-add /MathOptInterface
     latex_platform = _IS_GITHUB_ACTIONS ? "docker" : "native"
     @time Documenter.makedocs(
         sitename = "JuMP",

docs/packages.toml

@@ -0,0 +1,114 @@
+# ============================= jump-dev packages ============================ #
+
+[AmplNLWriter]
+    rev = "v1.1.0"
+[BARON]
+    rev = "f5f4c9c8f27e0ef8644d65fb956f3bca5305b45e"
+[Cbc]
+    rev = "a78e129e32f11b5c00ee8acea75c3b2204b8297f"
+[Clp]
+    rev = "3358ee69d9918ab011d5a9aa6201ec50d1bad2a4"
+[CPLEX]
+    rev = "8e6f2112e9cc433085ed77de6712f715edead8fc"
+[CSDP]
+    rev = "3a2e4c7c48af7660a5ba258a4cb6549ab0970366"
+[DiffOpt]
+    rev = "cd24703fc929960197da28fe13ab4abf074f0022"
+    extension = true
+[Dualization]
+    rev = "13974285d5ed6f678e4b96aafb764dad5238aac0"
+[ECOS]
+    rev = "80d1a927b05b04360b7a8e6800f5ae13bc6a1494"
+[GLPK]
+    rev = "dd835dc425fe8995d965da8a57b4a3a1764cf8da"
+[Gurobi]
+    rev = "72ee279373d7559e32050c35735d3fc803a7bb12"
+[HiGHS]
+    rev = "b0ab8361558fc63873a5cf380d335409f02d8863"
+[Ipopt]
+    rev = "v1.2.1"
+[KNITRO]
+    rev = "3fb7c61e886b1b06d9f5cd646e194da638c93355"
+[MiniZinc]
+    rev = "21d5829c2838959e2ec2d2952495c83f43b271b7"
+[MosekTools]
+    rev = "e2ed9bc174c6aaa68e457077529d49be52ecbc37"
+[MultiObjectiveAlgorithms]
+    rev = "b4413a1ef3b7d28045cedba4e68e5e4959c8bb12"
+    has_html = true
+[Pajarito]
+    rev = "2c008ee52bff34c41ebd394e2daae9eb32387e4b"
+[Pavito]
+    rev = "c0f3d81d9e9fff2963b872cf84fea35bfcf8b1d1"
+[Penopt]
+    rev = "486f07d3f3a11f12012ea3ada702a3ee55c8fdc5"
+[PolyJuMP]
+    rev = "0832380ae36ec66ebe4cbc9555ba351d67096693"
+    extension = true
+[SCS]
+    rev = "ef7cb4e38e987fcbbdeebd50bd4c211633328150"
+[SDPA]
+    rev = "5d15d3c292cd25b461f524aaaf8eb5ecb8e08b0d"
+[SDPNAL]
+    rev = "00a3fa19f4e1235587948113b0b681da17f4dab5"
+[SDPT3]
+    rev = "b565aac2a58818090d521f2340e71f597688e4fb"
+[SeDuMi]
+    rev = "47b4497cab3ce59ec7f65cff455bb2014981d4b4"
+[SumOfSquares]
+    rev = "0a3055533684d3ddf5d80162d2a6acf5acdf4373"
+    extension = true
+[Xpress]
+    rev = "b98347c49ba05953e29e5a1ef27d0d161780e19d"
+
+# =========================== non-jump-dev packages ========================== #
+
+# [Alpine]
+#   user = "lanl-ansi"
+# [CDCS]
+#   user = "oxfordcontrol"
+# [CDDLib]
+#   user = "JuliaPolyhedra"
+# [Clarabel]
+#   user = "oxfordcontrol"
+#   has_html = true
+# [COPT]
+#   user = "COPT-Public"
+# [COSMO]
+#   user = "oxfordcontrol"
+#   has_html = true
+# [DAQP]
+#   user = "darnstrom"
+#   rev = "main"
+# [EAGO]
+#   user = "PSORLab"
+# [GAMS]
+#   user = "GAMS-dev"
+# [Hypatia]
+#   user = "chriscoey"
+# [Juniper]
+#   user = "lanl-ansi"
+# [MadNLP]
+#   user = "MadNLP"
+[NEOSServer]
+  user = "odow"
+  rev = "v1.0.2"
+# [NLopt]
+#   user = "JuliaOpt"
+# [OSQP]
+#   user = "osqp"
+[PATHSolver]
+  user = "chkwon"
+  rev = "08848c165747695e7a4dcbb86a657e2347ca7149"
+# [ProxSDP]
+#   user = "mariohsouto"
+[SCIP]
+  user = "scipopt"
+  rev = "f4227ecac9f6984996ba3b22519982d24f54a245"
+[SDDP]
+    user = "odow"
+    rev = "ac47986f026ff94d512f85d1e850cc6a9df4f963"
+    has_html = true
+    extension = true
+# [Tulip]
+#   user = "ds4dm"

docs/src/packages/extensions.md

@@ -0,0 +1,9 @@
+# Introduction
+
+This section of the documentation contains brief documentation for some popular
+JuMP extensions. The list of extensions is not exhaustive, but instead is
+intended to help you discover popular JuMP extensions, and to give you an
+overview of the types of extensions that are possible to write with JuMP.
+
+Packages beginning with `jump-dev/` are developed and maintained by the
+JuMP developers. Other packages are developed independently.

docs/src/packages/solvers.md

@@ -0,0 +1,8 @@
+# Introduction
+
+This section of the documentation contains brief documentation for some of the
+solvers that JuMP supports. The list of solvers is not exhaustive, but instead
+is intended to help you discover commonly used solvers.
+
+Packages beginning with `jump-dev/` are developed and maintained by the
+JuMP developers. Other packages are developed independently.

docs/src/tutorials/getting_started/getting_started_with_julia.jl

@@ -251,7 +251,7 @@ isapprox(1e-9, 0.0; atol = 1e-8)
 
 # ## Vectors, matrices and arrays
 
-# Similar to Matlab, Julia has native support for vectors, matrices and tensors;
+# Similar to MATLAB, Julia has native support for vectors, matrices and tensors;
 # all of which are represented by arrays of different dimensions. Vectors are
 # constructed by comma-separated elements surrounded by square brackets:
 
@@ -491,12 +491,12 @@ for (key, value) in Dict("A" => 1, "B" => 2.5, "D" => 2 - 3im)
     println("$(key): $(value)")
 end
 
-# Note that in contrast to vector languages like Matlab and R, loops do not
+# Note that in contrast to vector languages like MATLAB and R, loops do not
 # result in a significant performance degradation in Julia.
 
 # ## Control flow
 
-# Julia control flow is similar to Matlab, using the keywords
+# Julia control flow is similar to MATLAB, using the keywords
 # `if-elseif-else-end`, and the logical operators `||` and `&&` for **or** and
 # **and** respectively:
 

docs/styles/Vocab/JuMP-Vocab/accept.txt

@@ -6,16 +6,18 @@ arXiv
 backports
 bikeshedding
 blogposts
-camelCase
 broadcasted
 [Bb]ugfix(?(es))
+camelCase
+codecov
 compat
 dataframe(?s)
 datastructure
 destructuring
 discretized
 docstring(?s)
 doctest(?s)
+embeddable
 [Ee]num(?s)
 errored
 flamegraph
@@ -28,6 +30,7 @@ jll|JLL
 [Mm]ultiline
 [Mm]ulticriteria
 namespace
+orthant
 performant
 [Pp]recompil(ation|(e(?d)))
 preprint
@@ -74,6 +77,7 @@ satisfiability
 scalarization(?s)
 [Ss]emi(continuous|integer|definite)
 subgradient
+subproblem(?s)
 subtour(?s)
 unboundedness
 unregister
@@ -92,6 +96,8 @@ Clp
 CPLEXLink
 Couenne
 Divio
+Dualization
+[Ee]mbotech
 [Ee]cos
 JSONSchema
 GLPK
@@ -100,14 +106,20 @@ GZip
 Ipopt
 Knitro
 KNITRO
+MATLAB
 MOI
 Mosek
 MOSEK
 Pajarito
+Pardiso
 PATHSolver
+Pavito
 Penbmi
+Penopt
 puzzlor
 RAPOSa
+SDPAFamily
+SDPNAL
 Xpress
 
 % People
@@ -116,6 +128,7 @@ Baldick
 Bertsimas
 Betts
 Bhatia
+Borchers
 Cholesky
 Coey
 Dantzig
@@ -136,11 +149,15 @@ Jiming
 Joaquim
 Kernighan
 Kallus
+Kaluba
+Kapelevich
 Latorre
+Legat
 Linial
 Luangkesorn
 Lubin
 Madani
+Marek
 Markowitz
 Mathieu
 Maurer
@@ -160,8 +177,10 @@ Stigler
 Taccari
 Tanneau
 Teghem
+Tillmann
 Ulungu
 Vandenberghe
+Vielma
 Wei
 Wollenberg
 Yu