Document all plotting functions and update documentation build structure

docs/make.jl

@@ -20,6 +20,7 @@ makedocs(;
         "Usage" => "usage.md",
         "optimization.md",
         "mesh.md",
+        "Plotting" => "plotting.md",
         "Internals" => "internals.md",
         "Docstrings" => "docstrings.md"
     ],

docs/src/mesh.md

@@ -14,9 +14,11 @@ MRSTWrapMesh
 
 ## Plotting functions
 
-Plotting requires that a Makie backend is loaded (typically GLMakie or CairoMakie). The documentation uses `CairoMakie` to work on machines without OpenGL enabled, but if you want fast and interactive plots, `GLMakie` should be preferred.
+Plotting requires that a Makie backend is loaded (typically GLMakie or CairoMakie). For comprehensive plotting documentation and examples, see the [Plotting](plotting.md) section.
 
-### Non-mutating
+### Basic mesh plotting
+
+#### Non-mutating
 
 ```@docs
 plot_mesh
@@ -25,7 +27,7 @@ plot_mesh_edges
 plot_interactive
 ```
 
-### Mutating
+#### Mutating
 
 ```@docs
 plot_mesh!

docs/src/plotting.md

@@ -0,0 +1,131 @@
+# Plotting and Visualization
+
+Jutul.jl provides comprehensive plotting capabilities for mesh visualization, performance analysis, and model structure visualization. All plotting functionality requires a Makie backend to be loaded.
+
+## Requirements
+
+Plotting requires that a Makie backend is loaded (typically GLMakie or CairoMakie). The documentation uses `CairoMakie` to work on machines without OpenGL enabled, but if you want fast and interactive plots, `GLMakie` should be preferred.
+
+```julia
+using GLMakie  # For interactive plots
+# or
+using CairoMakie  # For static plots/headless systems
+```
+
+## Mesh Visualization
+
+### Basic mesh plotting
+
+```@docs
+plot_mesh
+plot_mesh!
+plot_cell_data
+plot_cell_data!
+plot_mesh_edges
+plot_mesh_edges!
+```
+
+### Interactive plotting
+
+```@docs
+plot_interactive
+plot_multimodel_interactive
+```
+
+## Performance Analysis
+
+These functions help analyze simulation performance and solver behavior.
+
+```@docs
+plot_solve_breakdown
+plot_cumulative_solve
+plot_cumulative_solve!
+plot_linear_convergence
+plot_linear_convergence!
+```
+
+## Model Structure Visualization
+
+These functions require the GraphMakie.jl package to be loaded in addition to a Makie backend.
+
+```julia
+using GraphMakie
+```
+
+```@docs
+plot_variable_graph
+plot_model_graph
+```
+
+## Utilities
+
+```@docs
+check_plotting_availability
+```
+
+## Examples
+
+### Basic mesh plotting
+
+```julia
+using Jutul, CairoMakie
+
+# Create a simple mesh
+nx, ny = 10, 5
+mesh = CartesianMesh((nx, ny), (100.0, 50.0))
+
+# Plot the mesh structure
+fig, ax, p = plot_mesh(mesh)
+
+# Plot cell data with values
+cell_values = 1:number_of_cells(mesh)
+fig, ax, p = plot_cell_data(mesh, cell_values)
+
+# Add mesh edges
+plot_mesh_edges!(ax, mesh)
+fig
+```
+
+### Performance analysis
+
+```julia
+using Jutul, CairoMakie
+
+# After running simulations and collecting reports
+reports = [report1, report2, report3]
+names = ["Configuration A", "Configuration B", "Configuration C"]
+
+# Plot solver breakdown
+fig, data = plot_solve_breakdown(reports, names)
+
+# Plot cumulative solve time
+fig, ax, alldata, t = plot_cumulative_solve(reports, names = names)
+
+# Plot linear convergence for a single report
+fig = plot_linear_convergence(reports[1])
+```
+
+### Interactive visualization
+
+```julia
+using Jutul, GLMakie
+
+# Create mesh and simulation states
+mesh = CartesianMesh((10, 10, 5), (100.0, 100.0, 50.0))
+states = [state1, state2, state3, ...]  # From simulation
+
+# Launch interactive plot
+plot_interactive(mesh, states)
+```
+
+### Model structure visualization
+
+```julia
+using Jutul, GraphMakie, GLMakie
+
+# Plot variable dependencies
+fig = plot_variable_graph(model)
+
+# For multi-models, plot the full structure
+fig = plot_model_graph(multimodel)
+```

ext/JutulGraphMakieExt/JutulGraphMakieExt.jl

@@ -3,6 +3,27 @@ module JutulGraphMakieExt
     using Jutul, Makie
     using GraphMakie, Graphs, LayeredLayouts, NetworkLayout
 
+    """
+        plot_variable_graph(model)
+
+    Plot a graph visualization of variable dependencies in a simulation model.
+
+    # Arguments
+    - `model`: A Jutul simulation model
+
+    # Returns
+    - `fig`: Figure object containing the variable dependency graph
+
+    This function creates a directed graph showing the relationships between primary
+    variables, secondary variables, and parameters in the simulation model. Different
+    node types are color-coded:
+    - Primary variables: Blue  
+    - Secondary variables: Orange
+    - Parameters: Green
+
+    The graph layout uses a layered approach to clearly show the dependency structure
+    and data flow within the model.
+    """
     function Jutul.plot_variable_graph(model)
         graph, nodes, = build_variable_graph(model, to_graph = true)
         c1 = Makie.ColorSchemes.tab10[1]
@@ -76,6 +97,31 @@ module JutulGraphMakieExt
         )
     end
 
+    """
+        plot_model_graph(model; kwarg...)
+
+    Plot a graph visualization of model structure and equation relationships.
+
+    # Arguments
+    - `model`: A Jutul simulation model (can be `MultiModel` or single model)
+
+    # Keyword Arguments
+    - Additional keyword arguments are passed to the plotting functions
+
+    # Returns
+    - Plot object containing the model structure graph
+
+    For single models, this is equivalent to `plot_variable_graph`. For `MultiModel`
+    instances, this creates a more complex graph showing:
+    - Individual model components (colored by model)
+    - Equations within each model  
+    - Cross-term relationships between models
+    - Edge labels indicating cross-term types
+
+    The visualization helps understand the coupling structure in multi-physics
+    simulations and can be useful for debugging model setup and analyzing
+    computational dependencies.
+    """
     function Jutul.plot_model_graph(model; kwarg...)
         Jutul.plot_variable_graph(model; kwarg...)
     end

ext/JutulMakieExt/performance.jl

@@ -1,3 +1,23 @@
+"""
+    plot_solve_breakdown(allreports, names; per_it = false, include_local_solves = nothing, t_scale = ("s", 1.0))
+
+Plot a breakdown of solver performance timing for multiple simulation reports.
+
+# Arguments
+- `allreports`: Vector of simulation reports to analyze
+- `names`: Vector of names for each report (used for labeling)
+
+# Keyword Arguments
+- `per_it = false`: If `true`, show time per iteration instead of total time
+- `include_local_solves = nothing`: Whether to include local solve timing (auto-detected if `nothing`)
+- `t_scale = ("s", 1.0)`: Time scale unit and conversion factor for display
+
+# Returns
+- `(fig, D)`: Figure object and processed timing data
+
+This function creates a bar chart showing the breakdown of computational time spent
+in different parts of the simulation: assembly, local solves, linear solve, and total time.
+"""
 function Jutul.plot_solve_breakdown(allreports, names; per_it = false, include_local_solves = nothing, t_scale = ("s", 1.0))
     t_unit, t_num = t_scale
     if per_it
@@ -47,13 +67,68 @@ function Jutul.plot_solve_breakdown(allreports, names; per_it = false, include_l
     return (fig, D)
 end
 
+"""
+    plot_cumulative_solve(allreports, args...; kwarg...)
+
+Plot cumulative solver performance over time or steps for multiple simulation reports.
+
+# Arguments
+- `allreports`: Vector of simulation reports to analyze
+- `args...`: Additional arguments passed to `plot_cumulative_solve!`
+
+# Keyword Arguments
+- `use_time = false`: Plot wall time instead of iterations
+- `cumulative = true`: Show cumulative values vs individual step values
+- `x_is_time = true`: Use time on x-axis instead of step numbers
+- `legend = true`: Show legend for multiple datasets
+- `scatter_points = true`: Add scatter points to the plot
+- `linewidth = 3.5`: Line width for the plot
+- Additional keyword arguments are passed to the plotting functions
+
+# Returns
+- `(fig, ax, alldata, t)`: Figure, axis, processed data, and time vectors
+
+Creates a new figure and plots cumulative solver performance metrics, useful for
+comparing simulation efficiency across different configurations or time periods.
+"""
 function Jutul.plot_cumulative_solve(allreports, arg...; kwarg...)
     fig = Figure()
     ax, alldata, t = Jutul.plot_cumulative_solve!(fig[1, 1], allreports, arg...; kwarg...)
     display(fig)
     return (fig, ax, alldata, t)
 end
 
+"""
+    plot_cumulative_solve!(f, allreports, dt = nothing, names = nothing; kwarg...)
+
+Mutating version of `plot_cumulative_solve` that plots into an existing figure layout.
+
+# Arguments
+- `f`: Figure or layout position to plot into
+- `allreports`: Vector of simulation reports to analyze
+- `dt = nothing`: Time step sizes (auto-detected if `nothing`)
+- `names = nothing`: Names for each dataset (auto-generated if `nothing`)
+
+# Keyword Arguments
+- `use_time = false`: Plot wall time instead of iterations
+- `use_title = true`: Show plot title
+- `linewidth = 3.5`: Line width for the plot
+- `cumulative = true`: Show cumulative values vs individual step values
+- `linestyles = missing`: Custom line styles for each dataset
+- `colormap = :tab20`: Colormap for multiple datasets
+- `t_scale = ("s", 1.0)`: Time scale unit and conversion factor
+- `x_is_time = true`: Use time on x-axis instead of step numbers
+- `legend = true`: Show legend for multiple datasets
+- `ministeps = false`: Include ministep information
+- `title = nothing`: Custom plot title
+- `scatter_points = true`: Add scatter points to the plot
+
+# Returns
+- `(ax, alldata, t)`: Axis object, processed data, and time vectors
+
+This function provides fine-grained control over cumulative performance plotting
+by allowing integration into custom figure layouts.
+"""
 function Jutul.plot_cumulative_solve!(f, allreports, dt = nothing, names = nothing; 
         use_time = false,
         use_title = true,
@@ -156,13 +231,44 @@ function Jutul.plot_cumulative_solve!(f, allreports, dt = nothing, names = nothi
 end
 
 
+"""
+    plot_linear_convergence(report; kwarg...)
+
+Plot the convergence history of linear solver iterations from a simulation report.
+
+# Arguments
+- `report`: Simulation report containing linear solver information
+
+# Keyword Arguments
+- Additional keyword arguments are passed to the `Axis` constructor
+
+# Returns
+- `fig`: Figure object containing the convergence plot
+
+Creates a logarithmic plot showing how the linear solver residual decreases over
+iterations. This is useful for analyzing linear solver performance and convergence
+behavior during simulation.
+"""
 function Jutul.plot_linear_convergence(report; kwarg...)
     fig = Figure()
     ax = Axis(fig[1, 1], yscale = log10; ylabel = "Residual", xlabel = "Linear iterations", kwarg...)
     plot_linear_convergence!(ax, report)
     return fig
 end
 
+"""
+    plot_linear_convergence!(ax, report)
+
+Mutating version of `plot_linear_convergence` that plots into an existing axis.
+
+# Arguments
+- `ax`: Makie Axis object to plot into
+- `report`: Simulation report or vector of reports containing linear solver information
+
+This function extracts linear solver residual information from simulation reports
+and plots the convergence history. It can handle individual reports, nested report
+structures with ministeps, or vectors of multiple reports.
+"""
 function Jutul.plot_linear_convergence!(ax, report::AbstractDict)
     if haskey(report, :ministeps)
         plot_linear_convergence!(ax, report[:ministeps])

src/ext/graphmakie_ext.jl

@@ -1,9 +1,25 @@
 export plot_variable_graph, plot_model_graph
 
+"""
+    plot_variable_graph(model)
+
+Plot a graph visualization of variable dependencies in a simulation model.
+This function is implemented when GraphMakie is loaded.
+
+See the GraphMakie extension documentation for detailed arguments and usage.
+"""
 function plot_variable_graph
 
 end
 
+"""
+    plot_model_graph(model; kwarg...)
+
+Plot a graph visualization of model structure and equation relationships.
+This function is implemented when GraphMakie is loaded.
+
+See the GraphMakie extension documentation for detailed arguments and usage.
+"""
 function plot_model_graph
 
 end