Documentation generation

Purpose

The Zig project ships three flavors of documentation, all generated from this repository:

1. The language reference — doc/langref.html, built from doc/langref.html.in plus snippets in doc/langref/.
2. The standard library autodoc — built from lib/std/ and served either as a static site or via zig std.
3. The package manager spec — doc/build.zig.zon.md.

Language reference

File	Purpose
doc/langref.html.in (~351 KB)	The HTML template with embedded {#code_begin#}/{#code_end#} tags marking Zig code samples.
doc/langref/	Per-snippet .zig files (one per documented example).
tools/docgen.zig (~39 KB)	Runs the template through a small DSL, expands snippets, and produces langref.html.
tools/doctest.zig (~66 KB)	Compiles each snippet with a real zig and asserts that its compilation/runtime output matches what the docs claim.
build.zig (langref step)	Wires docgen and doctest into zig build langref.
tools/migrate_langref.zig	One-off migration script (legacy).

The flow:

graph LR
  in["doc/langref.html.in"] --> docgen["tools/docgen.zig"]
  snip["doc/langref/*.zig"] --> doctest["tools/doctest.zig"]
  doctest --> docgen
  docgen --> out["doc/langref.html"]
  super["-Denable-superhtml"] -->|optional| out

-Denable-superhtml adds an HTML validation pass over the output.

Standard library autodoc

The autodoc generator is built into the compiler itself: --emit-docs (and the getEmittedDocs() helper used by build.zig) produces a JSON+HTML bundle for any compiled module. build.zig wires this for lib/std/:

const autodoc_test = b.addObject(.{
    .name = "std",
    .zig_lib_dir = b.path("lib"),
    .root_module = b.createModule(.{
        .root_source_file = b.path("lib/std/std.zig"),
        .target = target,
        .optimize = .Debug,
    }),
});
const install_std_docs = b.addInstallDirectory(.{
    .source_dir = autodoc_test.getEmittedDocs(),
    .install_dir = .prefix,
    .install_subdir = "doc/std",
});

zig build std-docs produces zig-out/doc/std/. zig std (lib/compiler/std-docs.zig) serves the same data live.

Package manager spec

doc/build.zig.zon.md is hand-written Markdown documenting the manifest format consumed by src/Package/Manifest.zig.

Where to add documentation

• Language reference text: doc/langref.html.in.
• A new code example: add a .zig file under doc/langref/, reference it from langref.html.in, and doctest will compile/run it.
• Standard library: /// doc comments on the relevant declaration in lib/std/. They flow into the autodoc index automatically.
• build.zig.zon field: edit doc/build.zig.zon.md and the parser in src/Package/Manifest.zig.

Tests

zig build docs (and the more granular zig build langref / zig build std-docs) is part of the test matrix. CI scripts under ci/ run it on selected targets.

Key source files

File	Purpose
doc/langref.html.in	Language reference template.
doc/langref/	Per-snippet sources.
tools/docgen.zig	Template expander.
tools/doctest.zig	Snippet compiler/runner.
lib/compiler/std-docs.zig	zig std.
build.zig (langref, std-docs)	Build steps.
doc/build.zig.zon.md	Package manifest spec.