avsm/tutorials

OCaml Tutorial Creation

When to Use This Skill

Invoke this skill when:

• Creating tutorials for OCaml libraries
• Working with .mld documentation format
• Setting up MDX for executable examples
• Discussing interactive documentation

Overview

OCaml tutorials should:

• Introduce concepts gently
• Use executable code examples via MDX
• Progress from simple to complex
• Include practical patterns and use cases

File Structure

Required Components

1. doc/ directory in project root
2. tutorial.mld - Main tutorial content
3. index.mld - Documentation index
4. dune - Build rules

doc/dune Configuration

(mdx
 (files tutorial.mld)
 (libraries your_library_name))

(documentation
 (package your_package_name)
 (mld_files index tutorial))

dune-project Updates

Enable MDX:

(using mdx 0.4)

Add MDX as doc dependency:

(package
 (name your_package)
 (depends
  ...
  (mdx :with-doc)
  (odoc :with-doc)))

.mld Format

Document Structure

{0 Topic Name Tutorial}

Introduction text.

{1 Section Title}

Section content.

{2 Subsection Title}

Subsection content.

Executable Code Blocks

Use {@ocaml[...]} for executable examples:

{@ocaml[
# let x = 1 + 1;;
val x : int = 2
]}

• Lines starting with # are input
• Following lines are expected output
• MDX verifies output at build time
• Use ;; to terminate expressions

Non-Executable Code

Use {v ... v} for verbatim blocks:

{v
name: Alice
age: 30
v}

Cross-References

{!Library.function_name}          - Function reference
{!Library.Module.type_name}       - Type reference
{{!Library}API reference}         - Link with custom text

Lists

{ul
{- Item one}
{- Item two}
}

{ol
{- First item}
{- Second item}
}

Formatting

{b bold text}
{i italic text}

Tutorial Content Guidelines

Structure

1. Setup - How to load the library
2. Basic Usage - Simplest examples
3. Core Concepts - Main types and functions
4. Common Patterns - Real-world usage
5. Advanced Features - Complex functionality
6. Error Handling - How errors work
7. Summary - Quick reference

Setup Section

{1 Setup}

{@ocaml[
# #require "library_name";;
# open Library;;
]}

Best Practices

1. Show output - Include expected output in examples
2. Use consistent naming - Variables carry through examples
3. Build complexity gradually - Each example builds on previous
4. Explain the "why" - Not just syntax, but when to use features
5. Reference documentation - Link to API docs

Verification

dune build @check    # Verify syntax
dune build @doc      # Build documentation
dune runtest         # Run MDX tests (if configured)

Common Issues

Unresolved References

Use fully qualified names: {!Library.of_string} not {!of_string}

MDX Not Found

Enable in dune-project: (using mdx 0.4)

Output Mismatch

Run code manually, update expected output. Use <abstr> for abstract values.