Restructure documentation to remove API reference level

- Moved API reference content to index page (generated from make.jl)
- Removed separate API reference page level from navigation
- Reorganized all pages to show summaries before docstrings
- Updated pages.jl to have flat navigation structure
- All category pages now appear directly in sidebar
- Index page contains comprehensive API guidance and navigation

Documentation structure now follows:
- Home (with API reference) → Category pages directly
- Each page: Summary/Notes → Functions → Cache

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

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

Author: ChrisRackauckas

docs/make.jl

@@ -23,6 +23,50 @@ open(joinpath(@__DIR__, "src", "index.md"), "w") do io
     for line in eachline(joinpath(dirname(@__DIR__), "README.md"))
         println(io, line)
     end
+    
+    # Add API reference content
+    println(io, "")
+    println(io, "## API Reference")
+    println(io, "")
+    println(io, "```@docs")
+    println(io, "FiniteDiff")
+    println(io, "```")
+    println(io, "")
+    println(io, "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:")
+    println(io, "")
+    println(io, "### Function Categories")
+    println(io, "")
+    println(io, "- **[Derivatives](@ref derivatives)**: Single and multi-point derivatives of scalar functions")
+    println(io, "- **[Gradients](@ref gradients)**: Gradients of scalar-valued functions with respect to vector inputs")
+    println(io, "- **[Jacobians](@ref jacobians)**: Jacobian matrices of vector-valued functions, including sparse Jacobian support")
+    println(io, "- **[Hessians](@ref hessians)**: Hessian matrices of scalar-valued functions")
+    println(io, "- **[Jacobian-Vector Products](@ref jvp)**: Efficient computation of directional derivatives without forming full Jacobians")
+    println(io, "- **[Utilities](@ref utilities)**: Internal utilities and helper functions")
+    println(io, "")
+    println(io, "### Quick Start")
+    println(io, "")
+    println(io, "All functions follow a consistent API pattern:")
+    println(io, "")
+    println(io, "- **Cache-less versions**: `finite_difference_*` - convenient but allocate temporary arrays")
+    println(io, "- **In-place versions**: `finite_difference_*!` - efficient, non-allocating when used with caches")
+    println(io, "- **Cache constructors**: `*Cache` - pre-allocate work arrays for repeated computations")
+    println(io, "")
+    println(io, "### Method Selection")
+    println(io, "")
+    println(io, "Choose your finite difference method based on accuracy and performance needs:")
+    println(io, "")
+    println(io, "- **Forward differences**: Fast, `O(h)` accuracy, requires `O(n)` function evaluations")
+    println(io, "- **Central differences**: More accurate `O(h²)`, requires `O(2n)` function evaluations")
+    println(io, "- **Complex step**: Machine precision accuracy, `O(n)` evaluations, requires complex-analytic functions")
+    println(io, "")
+    println(io, "### Performance Tips")
+    println(io, "")
+    println(io, "1. **Use caches** for repeated computations to avoid allocations")
+    println(io, "2. **Consider sparsity** for large Jacobians with known sparsity patterns")
+    println(io, "3. **Choose appropriate methods** based on your accuracy requirements")
+    println(io, "4. **Leverage JVPs** when you only need directional derivatives")
+    println(io, "")
+    
     for line in eachline(joinpath(@__DIR__, "src", "reproducibility.md"))
         println(io, line)
     end

docs/pages.jl

@@ -3,13 +3,10 @@
 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"
-    ]
+    "Derivatives" => "derivatives.md",
+    "Gradients" => "gradients.md", 
+    "Jacobians" => "jacobians.md",
+    "Hessians" => "hessians.md",
+    "Jacobian-Vector Products" => "jvp.md",
+    "Utilities" => "utilities.md"
 ]

docs/src/api.md

@@ -2,6 +2,16 @@
 
 Functions for computing derivatives of scalar-valued functions.
 
+## Overview
+
+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`.
+
 ## Functions
 
 ```@docs
@@ -13,14 +23,4 @@ FiniteDiff.finite_difference_derivative!
 
 ```@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/derivatives.md

@@ -2,19 +2,6 @@
 
 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:
@@ -35,4 +22,17 @@ 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
+- Consider aliasing existing arrays into the cache for memory efficiency
+
+## Functions
+
+```@docs
+FiniteDiff.finite_difference_gradient
+FiniteDiff.finite_difference_gradient!
+```
+
+## Cache
+
+```@docs
+FiniteDiff.GradientCache
+```

docs/src/gradients.md

@@ -2,19 +2,6 @@
 
 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:
@@ -42,4 +29,17 @@ where `eᵢ` is the i-th unit vector and `hᵢ` is the step size in dimension i.
 
 ## StaticArrays Support
 
-The cache constructor automatically detects `StaticArray` types and adjusts the `inplace` parameter accordingly for optimal performance.
+The cache constructor automatically detects `StaticArray` types and adjusts the `inplace` parameter accordingly for optimal performance.
+
+## Functions
+
+```@docs
+FiniteDiff.finite_difference_hessian
+FiniteDiff.finite_difference_hessian!
+```
+
+## Cache
+
+```@docs
+FiniteDiff.HessianCache
+```

docs/src/hessians.md

@@ -2,19 +2,6 @@
 
 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:
@@ -38,4 +25,17 @@ FiniteDiff.jl provides efficient sparse Jacobian computation using graph colorin
 - **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.
+For non-square Jacobians, specify the output vector `fx` when creating the cache to ensure proper sizing.
+
+## Functions
+
+```@docs
+FiniteDiff.finite_difference_jacobian
+FiniteDiff.finite_difference_jacobian!
+```
+
+## Cache
+
+```@docs
+FiniteDiff.JacobianCache
+```

docs/src/jacobians.md

@@ -2,19 +2,6 @@
 
 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:
@@ -45,4 +32,17 @@ JVP is particularly useful for:
 ## 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
+- **In-place functions**: For in-place function evaluation, ensure proper cache sizing
+
+## Functions
+
+```@docs
+FiniteDiff.finite_difference_jvp
+FiniteDiff.finite_difference_jvp!
+```
+
+## Cache
+
+```@docs
+FiniteDiff.JVPCache
+```