docs!: Revamp documentation (#66)

- BREAKING CHANGE: rename `plot_instance` to `plot_context`, and `plot_solution` to `plot_sample`
- Global revamp of the documentation, with a complete description page for every benchmark problem.
- New `Plots` extension containing the plotting code for benchmarks
- New `DataSample` copy constructor
- Split API page between public and private methods

Author: BatyLeo

README.md

@@ -23,6 +23,13 @@ maximizer = generate_maximizer(bench)
 
 For the full list of benchmarks, the common interface, and detailed usage examples, refer to the [documentation](https://JuliaDecisionFocusedLearning.github.io/DecisionFocusedLearningBenchmarks.jl/stable/).
 
+## Installation
+
+```julia
+using Pkg
+Pkg.add("DecisionFocusedLearningBenchmarks")
+```
+
 ## Related Packages
 
 This package is part of the [JuliaDecisionFocusedLearning](https://github.com/JuliaDecisionFocusedLearning) organization, and built to be compatible with other packages in the ecosystem:

docs/make.jl

@@ -5,11 +5,15 @@ using Literate
 md_dir = joinpath(@__DIR__, "src")
 tutorial_dir = joinpath(@__DIR__, "src", "tutorials")
 benchmarks_dir = joinpath(@__DIR__, "src", "benchmarks")
-api_dir = joinpath(@__DIR__, "src", "api")
 
 tutorial_files = readdir(tutorial_dir)
 md_tutorial_files = [split(file, ".")[1] * ".md" for file in tutorial_files]
-benchmark_files = [joinpath("benchmarks", e) for e in readdir(benchmarks_dir)]
+
+categories = [
+    "Static problems" => "static",
+    "Stochastic problems" => "stochastic",
+    "Dynamic problems" => "dynamic",
+]
 
 include_tutorial = true
 
@@ -20,6 +24,19 @@ if include_tutorial
     end
 end
 
+benchmark_sections = Pair{String,Vector{String}}[]
+
+for (label, subdir) in categories
+    dir = joinpath(benchmarks_dir, subdir)
+    jl_files = filter(f -> endswith(f, ".jl"), readdir(dir))
+    md_names = [splitext(f)[1] * ".md" for f in jl_files]
+    for file in jl_files
+        Literate.markdown(joinpath(dir, file), dir; documenter=true, execute=false)
+    end
+    md_paths = [joinpath("benchmarks", subdir, f) for f in md_names]
+    push!(benchmark_sections, label => md_paths)
+end
+
 makedocs(;
     modules=[DecisionFocusedLearningBenchmarks],
     authors="Members of JuliaDecisionFocusedLearning",
@@ -32,7 +49,7 @@ makedocs(;
             "Creating custom benchmarks" => "custom_benchmarks.md",
         ],
         "Tutorials" => include_tutorial ? md_tutorial_files : [],
-        "Benchmark problems list" => benchmark_files,
+        "Benchmarks" => benchmark_sections,
         "API reference" => "api.md",
     ],
 )
@@ -44,6 +61,13 @@ if include_tutorial
     end
 end
 
+for (_, subdir) in categories
+    dir = joinpath(benchmarks_dir, subdir)
+    for f in filter(f -> endswith(f, ".md"), readdir(dir))
+        rm(joinpath(dir, f); force=true)
+    end
+end
+
 deploydocs(;
     repo="github.com/JuliaDecisionFocusedLearning/DecisionFocusedLearningBenchmarks.jl",
     devbranch="main",

docs/src/api.md

@@ -1,157 +1,115 @@
 # API Reference
 
-## Interface
+## Public
 
-```@autodocs
-Modules = [DecisionFocusedLearningBenchmarks.Utils]
-Private = false
-```
+### Interface
 
 ```@autodocs
 Modules = [DecisionFocusedLearningBenchmarks.Utils]
-Public = false
+Private = false
 ```
 
-## Argmax2D
+### Argmax2D
 
 ```@autodocs
 Modules = [DecisionFocusedLearningBenchmarks.Argmax2D]
 Private = false
 ```
 
-```@autodocs
-Modules = [DecisionFocusedLearningBenchmarks.Argmax2D]
-Public = false
-```
-
-## Argmax
+### Argmax
 
 ```@autodocs
 Modules = [DecisionFocusedLearningBenchmarks.Argmax]
 Private = false
 ```
 
-```@autodocs
-Modules = [DecisionFocusedLearningBenchmarks.Argmax]
-Public = false
-```
-
-## Contextual Stochastic Argmax
+### Contextual Stochastic Argmax
 
 ```@autodocs
 Modules = [DecisionFocusedLearningBenchmarks.ContextualStochasticArgmax]
 Private = false
 ```
 
-```@autodocs
-Modules = [DecisionFocusedLearningBenchmarks.ContextualStochasticArgmax]
-Public = false
-```
-
-## Dynamic Vehicle Scheduling
+### Dynamic Vehicle Scheduling
 
 ```@autodocs
 Modules = [DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling]
 Private = false
 ```
 
-```@autodocs
-Modules = [DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling]
-Public = false
-```
-
-## Dynamic Assortment
+### Dynamic Assortment
 
 ```@autodocs
 Modules = [DecisionFocusedLearningBenchmarks.DynamicAssortment]
 Private = false
 ```
 
-```@autodocs
-Modules = [DecisionFocusedLearningBenchmarks.DynamicAssortment]
-Public = false
-```
-
-## Fixed-size shortest path
+### Fixed-size shortest path
 
 ```@autodocs
 Modules = [DecisionFocusedLearningBenchmarks.FixedSizeShortestPath]
 Private = false
 ```
 
-```@autodocs
-Modules = [DecisionFocusedLearningBenchmarks.FixedSizeShortestPath]
-Public = false
-```
-
-## Maintenance
+### Maintenance
 
 ```@autodocs
 Modules = [DecisionFocusedLearningBenchmarks.Maintenance]
 Private = false
 ```
 
-```@autodocs
-Modules = [DecisionFocusedLearningBenchmarks.Maintenance]
-Public = false
-```
-
-## Portfolio Optimization
+### Portfolio Optimization
 
 ```@autodocs
 Modules = [DecisionFocusedLearningBenchmarks.PortfolioOptimization]
 Private = false
 ```
 
-```@autodocs
-Modules = [DecisionFocusedLearningBenchmarks.PortfolioOptimization]
-Public = false
-```
-
-## Ranking
+### Ranking
 
 ```@autodocs
 Modules = [DecisionFocusedLearningBenchmarks.Ranking]
 Private = false
 ```
 
-```@autodocs
-Modules = [DecisionFocusedLearningBenchmarks.Ranking]
-Public = false
-```
-
-## Subset selection
+### Subset selection
 
 ```@autodocs
 Modules = [DecisionFocusedLearningBenchmarks.SubsetSelection]
 Private = false
 ```
 
-```@autodocs
-Modules = [DecisionFocusedLearningBenchmarks.SubsetSelection]
-Public = false
-```
-
-## Stochastic Vehicle Scheduling
+### Stochastic Vehicle Scheduling
 
 ```@autodocs
 Modules = [DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling]
 Private = false
 ```
 
-```@autodocs
-Modules = [DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling]
-Public = false
-```
-
-## Warcraft
+### Warcraft
 
 ```@autodocs
 Modules = [DecisionFocusedLearningBenchmarks.Warcraft]
 Private = false
 ```
 
-```@autodocs
-Modules = [DecisionFocusedLearningBenchmarks.Warcraft]
+## Internals
+
+```@autodocs
+Modules = [
+    DecisionFocusedLearningBenchmarks.Utils,
+    DecisionFocusedLearningBenchmarks.Argmax,
+    DecisionFocusedLearningBenchmarks.Argmax2D,
+    DecisionFocusedLearningBenchmarks.ContextualStochasticArgmax,
+    DecisionFocusedLearningBenchmarks.DynamicVehicleScheduling,
+    DecisionFocusedLearningBenchmarks.DynamicAssortment,
+    DecisionFocusedLearningBenchmarks.FixedSizeShortestPath,
+    DecisionFocusedLearningBenchmarks.Maintenance,
+    DecisionFocusedLearningBenchmarks.PortfolioOptimization,
+    DecisionFocusedLearningBenchmarks.Ranking,
+    DecisionFocusedLearningBenchmarks.SubsetSelection,
+    DecisionFocusedLearningBenchmarks.StochasticVehicleScheduling,
+    DecisionFocusedLearningBenchmarks.Warcraft,
+]
 Public = false
 ```