Documentation with Scribble | Schema Programming Part 19

In Racket, documentation is written in Racket. Scribble is a language for writing text, similar to Markdown but with the full power of a programming language.

Basic Scribble Document

Save this as manual.scrbl:

#lang scribble/manual

@title{My Library Manual}
@author{Your Name}

@section{Introduction}

This is a library that does @bold{amazing} things.
You can use it to calculate @code{(+ 1 1)}.

@section{API Reference}

@defproc[(add [a number?] [b number?]) number?]{
  Returns the sum of @racket[a] and @racket[b].
}

The @ Syntax

Scribble uses @ to enter "text mode".

• @bold{text} is a function call!
• @racket[code] formats code and—crucially—hyperlinks it to the documentation if standard library functions are used.

Generating Output

Run scribble from the command line:

raco scribble --html manual.scrbl

This generates a professional-looking HTML page (just like the official Racket docs).

Summary

Scribble treats documentation as code. It ensures that your docs are consistent, hyperlinked, and even tested (you can run examples inside docs!).