Add Literate.jl for executable tutorial generation

[gescholt]

Summary

Add Literate.jl as an [extras] dependency to generate markdown tutorials and documentation from executable Julia scripts, following the pattern used by DifferentialEquations.jl and other mature packages.

Motivation

Current situation:

• Examples in examples/ are static .jl scripts
• No guarantee examples stay synchronized with code
• Documentation examples might become outdated
• Users can't easily run examples as notebooks

With Literate.jl:

• ✅ Documentation stays in sync with code (generated from working scripts)
• ✅ Examples guaranteed to execute correctly
• ✅ Generate both .md docs and clean .jl scripts
• ✅ Can also generate Jupyter notebooks (.ipynb)
• ✅ Better learning experience for users

Julia Ecosystem Pattern

Many mature packages use Literate.jl for tutorials:

• DifferentialEquations.jl - All tutorials are literate scripts
• Plots.jl - Examples generated with Literate
• Flux.jl - Tutorials use Literate
• Makie.jl - Documentation examples via Literate

Implementation

1. Add to Project.toml

[extras]
Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

[targets]
test = ["Test"]
docs = ["Literate"]

Note: Added to [extras], not main dependencies - only needed for building docs.

2. Create Literate Tutorials

Location: examples/tutorials/

Example structure:

# examples/tutorials/campaign_workflow.jl

# # Campaign Analysis Workflow
#
# This tutorial demonstrates the complete workflow for analyzing
# a campaign of experiments.

using GlobtimPostProcessing

# ## Load Campaign Results
#
# First, load the campaign results from a directory:

campaign = load_campaign_results("path/to/campaign")

# ## Compute Statistics
#
# Aggregate statistics across all experiments:

stats = aggregate_campaign_statistics(campaign)

# ## Generate Summary
#
# Create a comprehensive summary:

summary = generate_complete_summary(
    campaign,
    include_errors=true,
    include_classification=true
)

# Display the summary
println(summary)

3. Build Script

Create docs/generate_tutorials.jl:

using Literate

TUTORIALS = [
    "campaign_workflow",
    "custom_reports",
    "error_analysis"
]

for tutorial in TUTORIALS
    input = joinpath(@__DIR__, "..", "examples", "tutorials", "$(tutorial).jl")
    output = joinpath(@__DIR__, "src", "tutorials")
    
    # Generate markdown
    Literate.markdown(input, output)
    
    # Generate notebook (optional)
    Literate.notebook(input, output)
    
    # Generate clean script
    Literate.script(input, joinpath(@__DIR__, "..", "examples", "generated"))
end

4. CI Integration

Add to .github/workflows/docs.yml or similar:

- name: Generate tutorials
  run: julia docs/generate_tutorials.jl

Tutorial Topics

Suggested initial tutorials:

1. Basic Campaign Analysis (campaign_workflow.jl)

   • Loading campaigns
   • Computing statistics
   • Generating summaries
   • Exporting reports

2. Error Analysis Deep Dive (error_analysis.jl)

   • Error categorization
   • Priority filtering
   • Actionable recommendations
   • Custom error reports

3. Advanced Workflows (advanced_analysis.jl)

   • Critical point classification
   • Landscape fidelity assessment
   • Quality diagnostics
   • Multi-format exports

4. Custom Report Generation (custom_reports.jl)

   • Defining custom metrics
   • Creating custom formatters
   • Integration with external tools

Benefits

For Users:

• Working, tested examples they can copy-paste
• Tutorials available as markdown, notebooks, or scripts
• Easy to modify and experiment with

For Maintainers:

• Examples tested in CI (if they break, build fails)
• Documentation auto-updates from working code
• Single source of truth for examples

For Package Quality:

• Better onboarding for new users
• Reduced "examples don't work" issues
• Professional documentation presentation

Tasks

• Add Literate.jl to [extras] in Project.toml
• Create examples/tutorials/ directory structure
• Write campaign_workflow.jl literate tutorial
• Write error_analysis.jl literate tutorial
• Create docs/generate_tutorials.jl build script
• Integrate tutorial generation into documentation workflow
• Update README with link to generated tutorials
• Add CI job to verify tutorials execute successfully
• Create CONTRIBUTING guide for writing literate tutorials

Example Output

From a single .jl file, Literate generates:

examples/tutorials/campaign_workflow.jl   # Source (literate script)
    ↓
docs/src/tutorials/campaign_workflow.md   # Markdown for docs
examples/generated/campaign_workflow.jl   # Clean script
docs/src/tutorials/campaign_workflow.ipynb # Jupyter notebook

Priority

MEDIUM - Documentation enhancement, improves user onboarding

Estimated Effort

1 week (setup, 2-3 tutorials, CI integration, documentation)

References

• Literate.jl Documentation
• DifferentialEquations.jl Tutorials (Literate example)
• Documenter.jl + Literate Integration