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

•doc/ directory in project root
•tutorial.mld - Main tutorial content
•index.mld - Documentation index
•dune - Build rules

doc/dune Configuration

dune

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

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

dune-project Updates

Enable MDX:

dune

(using mdx 0.4)

Add MDX as doc dependency:

dune

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

.mld Format

Document Structure

code

{0 Topic Name Tutorial}

Introduction text.

{1 Section Title}

Section content.

{2 Subsection Title}

Subsection content.

Executable Code Blocks

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

code

{@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:

code

{v
name: Alice
age: 30
v}

Cross-References

code

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

Lists

code

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

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

Formatting

code

{b bold text}
{i italic text}

Tutorial Content Guidelines

Structure

•Setup - How to load the library
•Basic Usage - Simplest examples
•Core Concepts - Main types and functions
•Common Patterns - Real-world usage
•Advanced Features - Complex functionality
•Error Handling - How errors work
•Summary - Quick reference

Setup Section

code

{1 Setup}

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

Best Practices

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

Verification

bash

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.