Cleanup readme and documentation pages

Author: BatyLeo

README.md

@@ -12,7 +12,8 @@
 
 ## What is Decision-Focused Learning?
 
-Decision-focused learning (DFL) is a paradigm that integrates machine learning prediction with combinatorial optimization to make better decisions under uncertainty. Unlike traditional "predict-then-optimize" approaches that optimize prediction accuracy independently of downstream decision quality, DFL directly optimizes end-to-end decision performance.
+Decision-Focused Learning (DFL) is a paradigm that integrates machine learning prediction with combinatorial optimization to make better decisions under uncertainty.
+Unlike traditional "predict-then-optimize" approaches that optimize prediction accuracy independently of downstream decision quality, DFL directly optimizes end-to-end decision performance.
 
 A typical DFL algorithm involves training a parametrized policy that combines a statistical predictor with an optimization component:
 
@@ -23,19 +24,19 @@ x \;\longrightarrow\; \boxed{\,\text{Statistical model } \varphi_w\,}
 ```
 
 Where:
-- **Instance** $x$: input data (e.g., features, context)
 - **Statistical model** $\varphi_w$: machine learning predictor (e.g., neural network)
-- **Parameters** $\theta$: predicted parameters for the optimization problem
 - **CO algorithm** $f$: combinatorial optimization solver
-- **Solution** $y$: final decision/solution
+- **Instance** $x$: input data (e.g., features, context)
+- **Parameters** $\theta$: predicted parameters for the optimization problem solved by `f`
+- **Solution** $y$: output decision/solution
 
 ## Package Overview
 
 **DecisionFocusedLearningBenchmarks.jl** provides a comprehensive collection of benchmark problems for evaluating decision-focused learning algorithms. The package offers:
 
 - **Standardized benchmark problems** spanning diverse application domains
-- **Common interfaces** for datasets, statistical models, and optimization components  
-- **Ready-to-use pipelines** compatible with [InferOpt.jl](https://github.com/JuliaDecisionFocusedLearning/InferOpt.jl) and the whole [JuliaDecisionFocusedLearning](https://github.com/JuliaDecisionFocusedLearning) ecosystem
+- **Common interfaces** for creating datasets, statistical models, and optimization algorithms
+- **Ready-to-use DFL policies** compatible with [InferOpt.jl](https://github.com/JuliaDecisionFocusedLearning/InferOpt.jl) and the whole [JuliaDecisionFocusedLearning](https://github.com/JuliaDecisionFocusedLearning) ecosystem
 - **Evaluation tools** for comparing algorithm performance
 
 ## Benchmark Categories
@@ -53,13 +54,13 @@ Single-stage optimization problems with no randomness involved:
 - [`WarcraftBenchmark`](@ref): shortest path on image maps
 
 ### Stochastic Benchmarks (`AbstractStochasticBenchmark`)  
-Single-stage problems with random noise affecting the objective:
+Single-stage optimization problems under uncertainty:
 - [`StochasticVehicleSchedulingBenchmark`](@ref): stochastic vehicle scheduling under delay uncertainty
 
 ### Dynamic Benchmarks (`AbstractDynamicBenchmark`)
 Multi-stage sequential decision-making problems:
 - [`DynamicVehicleSchedulingBenchmark`](@ref): multi-stage vehicle scheduling under customer uncertainty
-- [`DynamicAssortmentBenchmark`](@ref): sequential product assortment selection
+- [`DynamicAssortmentBenchmark`](@ref): sequential product assortment selection with endogenous uncertainty
 
 ## Getting Started
 
@@ -85,6 +86,8 @@ maximizer = generate_maximizer(benchmark)
 gap = compute_gap(benchmark, dataset, model, maximizer)
 ```
 
+The only component you need to customize is the training algorithm itself.
+
 ## 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/src/benchmark_interfaces.md

@@ -1,6 +1,6 @@
 # Understanding Benchmark Interface
 
-This guide explains how benchmarks work through common interfaces in DecisionFocusedLearningBenchmarks.jl.
+This guide explains how benchmarks work through the common interface of DecisionFocusedLearningBenchmarks.jl.
 Understanding this interface is essential for using existing benchmarks and implementing new ones.
 
 ## Core Concepts
@@ -46,9 +46,9 @@ Every benchmark must implement a data generation method:
 # Generate a single sample
 generate_sample(benchmark::AbstractBenchmark, rng::AbstractRNG; kwargs...) -> DataSample
 ```
-This method should generate a single `DataSample` given a random number generator and optional parameters.
+This method should output a single `DataSample` given a random number generator and optional parameters as keyword arguments.
 
-If needed, benchmarks can instead override the [`generate_dataset`](@ref) method to directly create the entire dataset:
+If needed, benchmarks can instead override the [`generate_dataset`](@ref) method to directly create an entire dataset of size `size`:
 ```julia
 generate_dataset(benchmark::AbstractBenchmark, size::Int; kwargs...) -> Vector{DataSample}
 ```
@@ -67,7 +67,7 @@ generate_statistical_model(benchmark::AbstractBenchmark; kwargs...)
 generate_maximizer(benchmark::AbstractBenchmark; kwargs...)
 ```
 
-The statistical model typically maps from features `x` to cost parameters `θ`.
+The statistical model typically maps features `x` to cost parameters `θ`.
 The maximizer solves optimization problems given cost parameters `θ` (and potentially additional problem dependent keyword arguments), returning decision `y`.
 
 ### Benchmark Policies
@@ -78,15 +78,15 @@ Benchmarks can provide baseline policies for comparison and evaluation:
 # Get baseline policies for comparison
 generate_policies(benchmark::AbstractBenchmark) -> Tuple{Policy}
 ```
-This returns a tuple of `Policy` objects representing different benchmark-specific policies:
+This returns a tuple of `Policy` objects representing different benchmark-specific policies.
+A `Policy` is just a function with a name and description:
 ```julia
 struct Policy{F}
     name::String
     description::String  
     policy_function::F
 end
 ```
-A `Policy` is just a function with a name and description.
 
 Policies can be evaluated across multiple instances/environments using:
 ```julia

docs/src/benchmarks/argmax.md

@@ -1 +1,4 @@
 # Argmax
+
+!!! warning
+    Documentation for this benchmark is still under development. Please refer to the source code and API for more details.

docs/src/benchmarks/fixed_size_shortest_path.md

@@ -2,3 +2,6 @@
 
 [`FixedSizeShortestPathBenchmark`](@ref) is a benchmark problem that consists of finding the shortest path in a grid graph between the top left and bottom right corners.
 In this benchmark, the grid size is the same for all instances.
+
+!!! warning
+    Documentation for this benchmark is still under development. Please refer to the source code and API for more details.

docs/src/benchmarks/portfolio_optimization.md

@@ -10,3 +10,6 @@ The goal is to predict asset prices $c$ and maximize the expected return of a po
 & x \geq 0
 \end{aligned}
 ```
+
+!!! warning
+    Documentation for this benchmark is still under development. Please refer to the source code and API for more details.

docs/src/benchmarks/ranking.md

@@ -1 +1,4 @@
 # Ranking
+
+!!! warning
+    Documentation for this benchmark is still under development. Please refer to the source code and API for more details.

docs/src/benchmarks/vsp.md

@@ -1,3 +1,6 @@
 # Stochastic Vehicle Scheduling
 
 [`StochasticVehicleSchedulingBenchmark`](@ref).
+
+!!! warning
+    Documentation for this benchmark is still under development. Please refer to the source code and API for more details.

docs/src/index.md

@@ -12,28 +12,31 @@
 
 ## What is Decision-Focused Learning?
 
-Decision-focused learning (DFL) is a paradigm that integrates machine learning prediction with combinatorial optimization to make better decisions under uncertainty. Unlike traditional "predict-then-optimize" approaches that optimize prediction accuracy independently of downstream decision quality, DFL directly optimizes end-to-end decision performance.
+Decision-Focused Learning (DFL) is a paradigm that integrates machine learning prediction with combinatorial optimization to make better decisions under uncertainty.
+Unlike traditional "predict-then-optimize" approaches that optimize prediction accuracy independently of downstream decision quality, DFL directly optimizes end-to-end decision performance.
 
 A typical DFL algorithm involves training a parametrized policy that combines a statistical predictor with an optimization component:
 
 ```math
-\xrightarrow{x} \boxed{\text{Statistical model } \varphi_w} \xrightarrow{\theta} \boxed{\text{CO algorithm } f} \xrightarrow{ y}
+x \;\longrightarrow\; \boxed{\,\text{Statistical model } \varphi_w\,} 
+\;\xrightarrow{\theta}\; \boxed{\,\text{CO algorithm } f\,} 
+\;\longrightarrow\; y
 ```
 
 Where:
-- **Instance** $x$: input data (e.g., features, context)
 - **Statistical model** $\varphi_w$: machine learning predictor (e.g., neural network)
-- **Parameters** $\theta$: predicted parameters for the optimization problem
 - **CO algorithm** $f$: combinatorial optimization solver
-- **Solution** $y$: final decision/solution
+- **Instance** $x$: input data (e.g., features, context)
+- **Parameters** $\theta$: predicted parameters for the optimization problem solved by `f`
+- **Solution** $y$: output decision/solution
 
 ## Package Overview
 
 **DecisionFocusedLearningBenchmarks.jl** provides a comprehensive collection of benchmark problems for evaluating decision-focused learning algorithms. The package offers:
 
 - **Standardized benchmark problems** spanning diverse application domains
-- **Common interfaces** for datasets, statistical models, and optimization components  
-- **Ready-to-use pipelines** compatible with [InferOpt.jl](https://github.com/JuliaDecisionFocusedLearning/InferOpt.jl) and the whole [JuliaDecisionFocusedLearning](https://github.com/JuliaDecisionFocusedLearning) ecosystem
+- **Common interfaces** for creating datasets, statistical models, and optimization algorithms
+- **Ready-to-use DFL policies** compatible with [InferOpt.jl](https://github.com/JuliaDecisionFocusedLearning/InferOpt.jl) and the whole [JuliaDecisionFocusedLearning](https://github.com/JuliaDecisionFocusedLearning) ecosystem
 - **Evaluation tools** for comparing algorithm performance
 
 ## Benchmark Categories
@@ -51,13 +54,13 @@ Single-stage optimization problems with no randomness involved:
 - [`WarcraftBenchmark`](@ref): shortest path on image maps
 
 ### Stochastic Benchmarks (`AbstractStochasticBenchmark`)  
-Single-stage problems with random noise affecting the objective:
+Single-stage optimization problems under uncertainty:
 - [`StochasticVehicleSchedulingBenchmark`](@ref): stochastic vehicle scheduling under delay uncertainty
 
 ### Dynamic Benchmarks (`AbstractDynamicBenchmark`)
 Multi-stage sequential decision-making problems:
 - [`DynamicVehicleSchedulingBenchmark`](@ref): multi-stage vehicle scheduling under customer uncertainty
-- [`DynamicAssortmentBenchmark`](@ref): sequential product assortment selection
+- [`DynamicAssortmentBenchmark`](@ref): sequential product assortment selection with endogenous uncertainty
 
 ## Getting Started
 
@@ -83,6 +86,8 @@ maximizer = generate_maximizer(benchmark)
 gap = compute_gap(benchmark, dataset, model, maximizer)
 ```
 
+The only component you need to customize is the training algorithm itself.
+
 ## 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: