[docs] add READMEs of supported solvers to the documentation

[odow]

Closes #3307.

I'll add a preview link once CI finishes: https://jump.dev/JuMP.jl/previews/PR3309/packages/AmplNLWriter/

There's a few critical blockers, most noticeably, the Markdown supported by GitHub READMEs is different to Documenter's Markdown...

Compare

to

So perhaps we need to control the documentation within JuMP? Thinking about it though, having all of the solvers within the JuMP documentation would make a big difference to new users. (I've been using Pyomo for a different project recently, and I struggled with just about everything related to using and installing a solver.)

[odow]

I guess we can control all of the READMEs within jump-dev, and we just say that any external solvers need to have a compatible README, or they need to provide a separate JuMP.md file that we can pull in if they want to appear in the docs.

[codecov]

Codecov Report

Patch coverage has no change and project coverage change: +0.02 🎉

Comparison is base (f4c11e4) 98.12% compared to head (fba933c) 98.14%.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #3309      +/-   ##
==========================================
+ Coverage   98.12%   98.14%   +0.02%     
==========================================
  Files          34       34              
  Lines        4750     4861     +111     
==========================================
+ Hits         4661     4771     +110     
- Misses         89       90       +1     

see 7 files with indirect coverage changes

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

[odow]

The other option is to use https://github.com/JuliaComputing/MultiDocumenter.jl like the SciML docs; https://docs.sciml.ai/Overview/stable/, but that seems overkill. It's okay if the solvers have their own documentation and the README is just a link to that.

[odow]

import MathOptInterface as MOI

function print_supported(optimizer; eltype = Float64)
    model = MOI.instantiate(optimizer)
    functions, sets, model_attrs = Any[], Any[], Any[]
    for name in names(MOI; all = true)
        x = getfield(MOI, name)
        if !(x isa Type)
            continue
        end
        if !isconcretetype(x)
            try
                x = x{eltype}
            catch
                continue
            end
        end
        if x <: MOI.AbstractSet
            push!(sets, x)
        elseif x <: MOI.AbstractFunction
            push!(functions, x)
        elseif x <: MOI.AbstractModelAttribute
            try
                attr = x()
                if MOI.supports(model, attr)
                    push!(model_attrs, attr)
                end
            catch
                # pass
            end
        end
    end
    obj_funcs = [MOI.ObjectiveFunction{F} for F in functions]
    println("## MathOptInterface API\n")
    n = MOI.get(model, MOI.SolverName())
    println("The $n optimizer supports the following constraints and attributes.\n")
    println("List of supported objective functions:\n")
    supported_obj_funcs = Any[
        replace(" * [`$attr`](@ref)", "MathOptInterface" => "MOI")
        for attr in obj_funcs if MOI.supports(model, attr())
    ]
    println(join(sort!(supported_obj_funcs), "\n"))
    supported_variable_sets = Any[]
    for S in sets
        ret = if S <: MOI.AbstractScalarSet
            !MOI.supports_constraint(model, MOI.VariableIndex, S) &&
            MOI.supports_add_constrained_variable(model, S)
        else
            !MOI.supports_constraint(model, MOI.VectorOfVariables, S) &&
            MOI.supports_add_constrained_variables(model, S)
        end
        if ret
            push!(
                supported_variable_sets,
                replace(" * [`$S`](@ref)", "MathOptInterface" => "MOI"),
            )
        end
    end
    if !isempty(supported_variable_sets)
        println("\nList of supported variable types:\n")
        println(join(sort!(supported_variable_sets), "\n"))
    end
    println("\nList of supported constraint types:\n")
    supported_constraints = Any[
        replace(" * [`$F`](@ref) in [`$S`](@ref)", "MathOptInterface" => "MOI")
        for S in sets, F in functions if MOI.supports_constraint(model, F, S)
    ]
    println(join(sort!(supported_constraints), "\n"))
    println("\nList of supported model attributes:\n")
    supported_model_attrs = Any[
        replace(" * [`$attr`](@ref)", "MathOptInterface" => "MOI")
        for attr in model_attrs
    ]
    println(join(sort!(supported_model_attrs), "\n"))
    return
end

import SCS
print_supported(SCS.Optimizer)

[odow]

what would be the steps for a solver to be conform to what is needed? I can do SCIP and re-add it

It's up to you really, but the more uniform with the others the better.

So make it look like the other READMEs. Add sections for Affiliation, License, Installation, Use with JuMP, Options. No typos, etc.

[odow]

I talked to @blegat last night about this. There is still plenty of changes we could make to the READMEs, but it's been a bit of a slog to get to this point, so my preference is to merge this, and then deal with the changes one-by-one, rather than playing this juggling game of updating 26 different READMEs at the same time.

[chriscoey]

Thanks for all the effort here! This will be nice

[odow]

I wonder if we should have a "Solvers" section, and an "Extensions" section so that we can advertise DiffOpt, SumOfSquares, PolyJuMP, PowerModels, SDDP.jl, InfiniteOpt, etc. There's no reason they couldn't also provide a JuMP.md file. It makes the ecosystem a lot more cohesive and easier for new users to find.

[odow]

Pyomo has https://pyomo.readthedocs.io/en/stable/contributed_packages/index.html.

[pulsipher]

I wonder if we should have a "Solvers" section, and an "Extensions" section so that we can advertise DiffOpt, SumOfSquares, PolyJuMP, PowerModels, SDDP.jl, InfiniteOpt, etc. There's no reason they couldn't also provide a JuMP.md file. It makes the ecosystem a lot more cohesive and easier for new users to find.

I am in favor of this.

[odow]

Okay, this is in a reasonable state. It now has a section for solvers and extensions. I'm in favor of merging this and adding new pages in a separate PR. No need to make this PR long-lived.