Restructure API documentation into separate pages

- Split single API page into organized category pages:
  - Overview (api.md) - Quick start and navigation
  - Derivatives - Single/multi-point derivative functions
  - Gradients - Gradient computation with detailed notes
  - Jacobians - Jacobian matrices including sparse support
  - Hessians - Hessian matrices with mathematical background
  - JVP - Jacobian-vector products for efficient directional derivatives
  - Utilities - Internal functions and helpers

- Updated pages.jl with hierarchical documentation structure
- Enhanced each page with category-specific guidance and examples
- Improved navigation with cross-references between sections
- Documentation builds successfully with clean sidebar organization

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: ChrisRackauckas

docs/pages.jl

@@ -1,3 +1,15 @@
 # Put in a separate page so it can be used by SciMLDocs.jl
 
-pages = ["Home" => "index.md", "tutorials.md", "api.md"]
+pages = [
+    "Home" => "index.md",
+    "Tutorials" => "tutorials.md",
+    "API Reference" => [
+        "Overview" => "api.md",
+        "Derivatives" => "derivatives.md",
+        "Gradients" => "gradients.md", 
+        "Jacobians" => "jacobians.md",
+        "Hessians" => "hessians.md",
+        "Jacobian-Vector Products" => "jvp.md",
+        "Utilities" => "utilities.md"
+    ]
+]

docs/src/api.md

@@ -1,69 +1,51 @@
-# API
+# API Reference
 
 ```@docs
 FiniteDiff
 ```
 
-## Derivatives
+FiniteDiff.jl provides fast, non-allocating finite difference calculations with support for sparsity patterns and various array types. The API is organized into several categories:
 
-```@docs
-FiniteDiff.finite_difference_derivative
-FiniteDiff.finite_difference_derivative!
-FiniteDiff.DerivativeCache
-```
+## Function Categories
 
-## Gradients
+### [Derivatives](@ref derivatives)
+Single and multi-point derivatives of scalar functions.
 
-```@docs
-FiniteDiff.finite_difference_gradient
-FiniteDiff.finite_difference_gradient!
-FiniteDiff.GradientCache
-```
+### [Gradients](@ref gradients)  
+Gradients of scalar-valued functions with respect to vector inputs.
 
-Gradients are either a vector->scalar map `f(x)`, or a scalar->vector map `f(fx,x)` if `inplace=Val{true}` and `fx=f(x)` if `inplace=Val{false}`.
+### [Jacobians](@ref jacobians)
+Jacobian matrices of vector-valued functions, including sparse Jacobian support.
 
-Note that here `fx` is a cached function call of `f`. If you provide `fx`, then
-`fx` will be used in the forward differencing method to skip a function call.
-It is on you to make sure that you update `cache.fx` every time before
-calling `FiniteDiff.finite_difference_gradient!`. If `fx` is an immutable, e.g. a scalar or 
-a `StaticArray`, `cache.fx` should be updated using `@set` from [Setfield.jl](https://github.com/jw3126/Setfield.jl).
-A good use of this is if you have a cache array for the output of `fx` already being used, you can make it alias
-into the differencing algorithm here.
+### [Hessians](@ref hessians)
+Hessian matrices of scalar-valued functions.
 
-## Jacobians
+### [Jacobian-Vector Products](@ref jvp)
+Efficient computation of directional derivatives without forming full Jacobians.
 
-```@docs
-FiniteDiff.finite_difference_jacobian
-FiniteDiff.finite_difference_jacobian!
-FiniteDiff.JacobianCache
-```
+### [Utilities](@ref utilities)
+Internal utilities and helper functions.
 
-Jacobians are for functions `f!(fx,x)` when using in-place `finite_difference_jacobian!`,
-and `fx = f(x)` when using out-of-place `finite_difference_jacobian`. The out-of-place
-jacobian will return a similar type as `jac_prototype` if it is not a `nothing`. For non-square
-Jacobians, a cache which specifies the vector `fx` is required.
+## Quick Start
 
-For sparse differentiation, pass a `colorvec` of matrix colors. `sparsity` should be a sparse
-or structured matrix (`Tridiagonal`, `Banded`, etc. according to the ArrayInterfaceCore.jl specs)
-to allow for decompression, otherwise the result will be the colorvec compressed Jacobian.
+All functions follow a consistent API pattern:
 
-## Hessians
+- **Cache-less versions**: `finite_difference_*` - convenient but allocate temporary arrays
+- **In-place versions**: `finite_difference_*!` - efficient, non-allocating when used with caches  
+- **Cache constructors**: `*Cache` - pre-allocate work arrays for repeated computations
 
-```@docs
-FiniteDiff.finite_difference_hessian
-FiniteDiff.finite_difference_hessian!
-FiniteDiff.HessianCache
-```
+## Method Selection
 
-Hessians are for functions `f(x)` which return a scalar.
+Choose your finite difference method based on accuracy and performance needs:
 
-## Jacobian-Vector Products (JVP)
+- **Forward differences**: Fast, `O(h)` accuracy, requires `O(n)` function evaluations
+- **Central differences**: More accurate `O(h²)`, requires `O(2n)` function evaluations
+- **Complex step**: Machine precision accuracy, `O(n)` evaluations, requires complex-analytic functions
 
-```@docs
-FiniteDiff.finite_difference_jvp
-FiniteDiff.finite_difference_jvp!
-FiniteDiff.JVPCache
-```
+## Performance Tips
 
-JVP functions compute the Jacobian-vector product `J(x) * v` efficiently without computing the full Jacobian matrix. This is particularly useful when you only need directional derivatives.
+1. **Use caches** for repeated computations to avoid allocations
+2. **Consider sparsity** for large Jacobians with known sparsity patterns
+3. **Choose appropriate methods** based on your accuracy requirements
+4. **Leverage JVPs** when you only need directional derivatives
 

docs/src/derivatives.md

@@ -0,0 +1,26 @@
+# Derivatives
+
+Functions for computing derivatives of scalar-valued functions.
+
+## Functions
+
+```@docs
+FiniteDiff.finite_difference_derivative
+FiniteDiff.finite_difference_derivative!
+```
+
+## Cache
+
+```@docs
+FiniteDiff.DerivativeCache
+```
+
+## Notes
+
+Derivatives are computed for scalar→scalar maps `f(x)` where `x` can be a single point or a collection of points. The derivative functions support:
+
+- **Forward differences**: `O(1)` function evaluation per point, `O(h)` accuracy
+- **Central differences**: `O(2)` function evaluations per point, `O(h²)` accuracy  
+- **Complex step**: `O(1)` function evaluation per point, machine precision accuracy
+
+For optimal performance with repeated computations, use the cached versions with `DerivativeCache`.

docs/src/gradients.md

@@ -0,0 +1,38 @@
+# Gradients
+
+Functions for computing gradients of scalar-valued functions with respect to vector inputs.
+
+## Functions
+
+```@docs
+FiniteDiff.finite_difference_gradient
+FiniteDiff.finite_difference_gradient!
+```
+
+## Cache
+
+```@docs
+FiniteDiff.GradientCache
+```
+
+## Function Types
+
+Gradients support two types of function mappings:
+
+- **Vector→scalar**: `f(x)` where `x` is a vector and `f` returns a scalar
+- **Scalar→vector**: `f(fx, x)` for in-place evaluation or `fx = f(x)` for out-of-place
+
+## Performance Notes
+
+- **Forward differences**: `O(n)` function evaluations, `O(h)` accuracy
+- **Central differences**: `O(2n)` function evaluations, `O(h²)` accuracy
+- **Complex step**: `O(n)` function evaluations, machine precision accuracy
+
+## Cache Management
+
+When using `GradientCache` with pre-computed function values:
+
+- If you provide `fx`, then `fx` will be used in forward differencing to skip a function call
+- You must update `cache.fx` before each call to `finite_difference_gradient!`
+- For immutable types (scalars, `StaticArray`), use `@set` from [Setfield.jl](https://github.com/jw3126/Setfield.jl)
+- Consider aliasing existing arrays into the cache for memory efficiency

docs/src/hessians.md

@@ -0,0 +1,45 @@
+# Hessians
+
+Functions for computing Hessian matrices of scalar-valued functions.
+
+## Functions
+
+```@docs
+FiniteDiff.finite_difference_hessian
+FiniteDiff.finite_difference_hessian!
+```
+
+## Cache
+
+```@docs
+FiniteDiff.HessianCache
+```
+
+## Function Requirements
+
+Hessian functions are designed for scalar-valued functions `f(x)` where:
+
+- `x` is a vector of parameters
+- `f(x)` returns a scalar value
+- The Hessian `H[i,j] = ∂²f/(∂x[i]∂x[j])` is automatically symmetrized
+
+## Mathematical Background
+
+For a scalar function `f: ℝⁿ → ℝ`, the Hessian central difference approximation is:
+
+```
+H[i,j] ≈ (f(x + eᵢhᵢ + eⱼhⱼ) - f(x + eᵢhᵢ - eⱼhⱼ) - f(x - eᵢhᵢ + eⱼhⱼ) + f(x - eᵢhᵢ - eⱼhⱼ)) / (4hᵢhⱼ)
+```
+
+where `eᵢ` is the i-th unit vector and `hᵢ` is the step size in dimension i.
+
+## Performance Considerations
+
+- **Complexity**: Requires `O(n²)` function evaluations for an n-dimensional input
+- **Accuracy**: Central differences provide `O(h²)` accuracy for second derivatives  
+- **Memory**: The result is returned as a `Symmetric` matrix view
+- **Alternative**: For large problems, consider computing the gradient twice instead
+
+## StaticArrays Support
+
+The cache constructor automatically detects `StaticArray` types and adjusts the `inplace` parameter accordingly for optimal performance.

docs/src/jacobians.md

@@ -0,0 +1,41 @@
+# Jacobians
+
+Functions for computing Jacobian matrices of vector-valued functions.
+
+## Functions
+
+```@docs
+FiniteDiff.finite_difference_jacobian
+FiniteDiff.finite_difference_jacobian!
+```
+
+## Cache
+
+```@docs
+FiniteDiff.JacobianCache
+```
+
+## Function Types
+
+Jacobians support the following function signatures:
+
+- **Out-of-place**: `fx = f(x)` where both `x` and `fx` are vectors
+- **In-place**: `f!(fx, x)` where `f!` modifies `fx` in-place
+
+## Sparse Jacobians
+
+FiniteDiff.jl provides efficient sparse Jacobian computation using graph coloring:
+
+- Pass a `colorvec` of matrix colors to enable column compression
+- Provide `sparsity` as a sparse or structured matrix (`Tridiagonal`, `Banded`, etc.)
+- Supports automatic sparsity pattern detection via ArrayInterfaceCore.jl
+- Results are automatically decompressed unless `sparsity=nothing`
+
+## Performance Notes
+
+- **Forward differences**: `O(n)` function evaluations, `O(h)` accuracy  
+- **Central differences**: `O(2n)` function evaluations, `O(h²)` accuracy
+- **Complex step**: `O(n)` function evaluations, machine precision accuracy
+- **Sparse Jacobians**: Use graph coloring to reduce function evaluations significantly
+
+For non-square Jacobians, specify the output vector `fx` when creating the cache to ensure proper sizing.

docs/src/jvp.md

@@ -0,0 +1,48 @@
+# Jacobian-Vector Products (JVP)
+
+Functions for computing Jacobian-vector products efficiently without forming the full Jacobian matrix.
+
+## Functions
+
+```@docs
+FiniteDiff.finite_difference_jvp
+FiniteDiff.finite_difference_jvp!
+```
+
+## Cache
+
+```@docs
+FiniteDiff.JVPCache
+```
+
+## Mathematical Background
+
+The JVP computes `J(x) * v` where `J(x)` is the Jacobian of function `f` at point `x` and `v` is a direction vector. This is computed using finite difference approximations:
+
+- **Forward**: `J(x) * v ≈ (f(x + h*v) - f(x)) / h`  
+- **Central**: `J(x) * v ≈ (f(x + h*v) - f(x - h*v)) / (2h)`
+
+where `h` is the step size and `v` is the direction vector.
+
+## Performance Benefits
+
+JVP functions are particularly efficient when you only need directional derivatives:
+
+- **Function evaluations**: Only 2 function evaluations (vs `O(n)` for full Jacobian)
+- **Forward differences**: 2 function evaluations, `O(h)` accuracy
+- **Central differences**: 2 function evaluations, `O(h²)` accuracy  
+- **Memory efficient**: No need to store the full Jacobian matrix
+
+## Use Cases
+
+JVP is particularly useful for:
+
+- **Optimization**: Computing directional derivatives along search directions
+- **Sparse directions**: When `v` has few non-zero entries
+- **Memory constraints**: Avoiding storage of large Jacobian matrices
+- **Newton methods**: Computing Newton steps `J⁻¹ * v` iteratively
+
+## Limitations
+
+- **Complex step**: JVP does not currently support complex step differentiation (`Val(:complex)`)
+- **In-place functions**: For in-place function evaluation, ensure proper cache sizing

docs/src/utilities.md

@@ -0,0 +1,31 @@
+# Utilities
+
+Internal utility functions and types that may be useful for advanced users.
+
+## Step Size Computation
+
+While these functions are primarily internal, they can be useful for understanding and customizing finite difference computations:
+
+### Default Step Sizes
+
+Different finite difference methods use different optimal step sizes to balance truncation error and round-off error:
+
+- **Forward differences**: `sqrt(eps(T))` - balances O(h) truncation error with round-off
+- **Central differences**: `cbrt(eps(T))` - balances O(h²) truncation error with round-off  
+- **Hessian central**: `eps(T)^(1/4)` - balances O(h²) truncation error for second derivatives
+
+### Complex Step Differentiation
+
+Complex step differentiation uses machine epsilon since it avoids subtractive cancellation:
+
+⚠️ **Important**: `f` must be a function of a real variable that is also complex analytic when the input is complex!
+
+## Array Utilities
+
+Internal utilities for handling different array types and ensuring compatibility:
+
+- `_vec(x)`: Vectorizes arrays while preserving scalars
+- `_mat(x)`: Ensures matrix format, converting vectors to column matrices
+- `setindex(x, v, i...)`: Non-mutating setindex for immutable arrays
+
+These functions help FiniteDiff.jl work with various array types including `StaticArrays`, structured matrices, and GPU arrays.