Add comprehensive API documentation and restructure docs organization

[ChrisRackauckas-Claude]

Summary

This PR comprehensively transforms FiniteDiff.jl documentation by adding detailed docstrings to all functions and completely restructuring the documentation organization for optimal usability.

Comprehensive Documentation Added

Main API Functions:

• Enhanced finite_difference_jacobian with mathematical background and usage examples
• Complete finite_difference_gradient documentation covering both vector→scalar and scalar→vector cases
• Detailed finite_difference_hessian with mathematical formulation and complexity analysis
• Complete finite_difference_jvp documentation explaining Jacobian-vector products
• All corresponding in-place (!) versions with comprehensive usage notes

Cache Constructors:

• Full documentation for JVPCache, GradientCache, HessianCache, DerivativeCache
• Both allocating and non-allocating constructor variants documented
• Clear guidance on when to use each approach for optimal performance

Internal Functions:

• Complete documentation for epsilon computation functions (compute_epsilon)
• Detailed default_relstep with mathematical justification for step size choices
• Documentation for sparse Jacobian utilities (_make_Ji, _colorediteration!)
• Array utility functions (_vec, _mat, setindex overloads) with clear purpose statements

Documentation Structure Reorganization

New Page Organization:

• Home: Package overview from README (clean, no API clutter)
• Tutorials: Existing tutorial content
• Derivatives: Single/multi-point scalar function derivatives
• Gradients: Vector→scalar and scalar→vector gradient computation
• Jacobians: Vector→vector functions with comprehensive sparse Jacobian guide
• Hessians: Scalar→matrix second derivatives with mathematical background
• Jacobian-Vector Products: Efficient directional derivatives without full Jacobians
• Step Size Selection: Mathematical theory and algorithms for optimal epsilon selection
• Internal Utilities: Complete coverage of internal functions for advanced users

Improved Content Organization:

• Explanations first: Each page provides context and theory before technical details
• Logical flow: Mathematical background → Performance notes → Function documentation
• Focused content: Each page concentrates on one functional area
• Educational value: Theory explanations help users understand when and how to use functions

Documentation Features

Mathematical Rigor:

• Error analysis for truncation vs round-off errors
• Optimal step size derivations for each finite difference method
• Complexity analysis (e.g., "O(n) function evaluations, O(h²) accuracy")
• Mathematical formulations for Hessian approximations

Practical Guidance:

• Comprehensive parameter descriptions with types and purpose
• Usage examples with working code snippets
• Performance characteristics and trade-offs
• Cache management best practices
• Sparse Jacobian computation guidelines

Professional Quality:

• Consistent Julia docstring formatting
• Mathematical notation using LaTeX-style formatting
• Cross-references between related functions
• SciMLStyle code formatting applied throughout

Technical Implementation

Code Quality:

• Applied JuliaFormatter with SciMLStyle to all modified files
• No breaking changes to existing API
• All existing tests continue to pass
• Added 40+ comprehensive docstrings following Julia conventions

Documentation Build System:

• Restructured docs/pages.jl for flat, intuitive navigation
• Updated docs/make.jl to generate clean index page from README
• Created 8 focused category pages replacing complex nested structure
• Documentation builds cleanly with proper cross-references

Impact and Benefits

For New Users

• Accessible entry point: Clear explanations of finite difference theory
• Learning progression: From basic concepts to advanced implementation details
• Practical examples: Working code snippets for all major functions
• Method selection guidance: When to use forward vs central vs complex step

For Experienced Users

• Complete reference: Detailed parameter documentation for all functions
• Performance optimization: Complexity analysis and cache usage guidelines
• Advanced features: Sparse Jacobian computation and JVP efficiency
• Internal understanding: Documentation of algorithms and design decisions

For Package Quality

• Professional appearance: Documentation quality now matches other top-tier Julia packages
• Educational value: Users learn finite difference theory alongside API usage
• Maintainability: Well-organized structure makes future updates easier
• Accessibility: Clear organization helps users find what they need quickly

Before vs After

Before: Minimal docstrings like "Cache-less."
After: Comprehensive documentation with mathematical background, examples, performance analysis, and clear usage guidance.

This transformation makes FiniteDiff.jl significantly more accessible while preserving its performance-focused nature and adding educational value for users learning numerical differentiation.

🤖 Generated with Claude Code

[ChrisRackauckas-Claude]

Latest Update: Documentation Restructuring

I've restructured the documentation based on feedback to improve organization and usability:

Changes Made

• Removed API reference layer: Eliminated the intermediate API reference page that was adding unnecessary navigation complexity
• Flat navigation structure: All function categories now appear directly in the sidebar (Home → Tutorials → Derivatives → Gradients → etc.)
• Reorganized page content: Each page now shows explanations and context before the technical docstrings
• Clean index page: Home page contains only README content and package overview

New Documentation Flow

1. Home: Package overview, installation, basic concepts
2. Category pages: Each has structured content:
   • Overview and explanation of the functionality
   • Performance notes and usage guidance
   • Mathematical background where relevant
   • Function docstrings (with all the comprehensive details added)
   • Cache documentation

Benefits

• Easier navigation: Direct access to each function category
• Better learning experience: Context provided before diving into technical details
• Professional appearance: Clean, organized structure similar to other high-quality Julia packages
• Comprehensive coverage: All the detailed docstrings are still included but better organized

The documentation now builds cleanly and provides an excellent user experience with the comprehensive API documentation properly structured.

🤖 Generated with Claude Code

[ChrisRackauckas-Claude]

Final Documentation Structure Update

Added the requested specialized pages and completed the documentation organization:

New Pages Added

📐 Step Size Selection (epsilons.md):

• Mathematical theory: Error analysis of truncation vs round-off error
• Optimal step sizes: Derivation of optimal step sizes for each method ( for forward, for central, etc.)
• Adaptive algorithms: How relative and absolute step sizes are combined
• Special cases: Complex step differentiation and sparse Jacobian considerations
• Practical guidance: When to use custom step sizes vs defaults

🔧 Internal Utilities (renamed and expanded utilities.md):

• Array utilities: Type conversion functions (, , overloads)
• Hessian utilities: Helper functions for Hessian computation
• Sparse Jacobian internals: Graph coloring algorithms and matrix construction
• Performance optimizations: Specialized functions for efficient computation
• Cache management: Resize functions and memory management
• Design philosophy: Explanation of internal design principles

Current Complete Structure

Each page follows the requested structure:

• Explanations and context first
• Mathematical background and theory
• Performance notes and guidance
• Detailed docstrings last

Key Benefits

1. Educational progression: From basic usage to advanced theory
2. Focused content: Each page concentrates on one aspect
3. Complete coverage: Both user-facing API and internal algorithms documented
4. Professional quality: Mathematical rigor with practical guidance

The documentation now provides a comprehensive learning path from basic usage through advanced implementation details, making FiniteDiff.jl accessible to users at all levels.

🤖 Generated with Claude Code

[ChrisRackauckas-Claude]

Final Documentation Structure Update

Added the requested specialized pages and completed the documentation organization:

New Pages Added

Step Size Selection (epsilons.md):

• Mathematical theory of error analysis (truncation vs round-off error)
• Optimal step sizes for each method (forward, central, complex step)
• Adaptive algorithms for combining relative and absolute step sizes
• Special cases for complex step differentiation and sparse Jacobians
• Practical guidance on when to customize step sizes

Internal Utilities (renamed and expanded utilities.md):

• Array utilities for type conversion and compatibility
• Hessian utilities for specialized matrix operations
• Sparse Jacobian internals including graph coloring algorithms
• Performance optimizations and sparsity detection functions
• Cache management and resize functions
• Design philosophy explaining internal implementation choices

Current Complete Structure

The documentation now has 8 focused pages:

1. Home (README + package overview)
2. Tutorials
3. Derivatives (scalar functions)
4. Gradients (vector-scalar and scalar-vector)
5. Jacobians (vector-vector with sparse support)
6. Hessians (scalar-matrix with mathematical background)
7. Jacobian-Vector Products (efficient directional derivatives)
8. Step Size Selection (epsilon theory and algorithms)
9. Internal Utilities (advanced/internal functions)

Each page follows the requested structure with explanations before docstrings, mathematical background, and performance guidance.

The documentation now provides comprehensive coverage from basic usage to advanced implementation details.

Generated with Claude Code