Generating the documentation

build.zig generates the docs when a build step installs std.Build.Step.Compile.getEmittedDocs, a function of b.addExecutable() and such -- even b.addTest(). For example here's a complete build.zig with only 'test' and 'docs' steps:

const std = @import("std");

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const test_step = b.step("test", "Run unit tests");
    const docs_step = b.step("docs", "Generate docs");

    const unit_tests = b.addTest(.{
        .name = "list1",
        .root_source_file = b.path("src/list1.zig"),
        .target = target,
        .optimize = optimize,
    });
    const run_unit_tests = b.addRunArtifact(unit_tests);
    test_step.dependOn(&run_unit_tests.step);
    b.installArtifact(unit_tests);

    const docs_install = b.addInstallDirectory(.{
        .source_dir = unit_tests.getEmittedDocs(),
        .install_dir = .prefix,
        .install_subdir = "docs",
    });
    docs_step.dependOn(&docs_install.step);
}

Generated files

The docs appear where artifacts are installed. A normal use of the last example puts the docs under zig-out/docs/

• index.html - loader for the UI
• main.js - driver for WASM
• main.wasm - Zig binary doing all the work
• sources.tar - as the name suggests, your source and the source of your dependencies, such as std

Viewing the documentation

For browser security reasons you can't just open index.html in a browser, not without including the JS and the WASM in the index.html file somehow. You'll need a webserver.

Although the 'zig' executable can serve std's documentation with zig std, the built-in webserver isn't exposed for reuse for your own documentation. You can use std.http.Server to write your own webserver in Zig and serve these files.

Once you have a webserver, the likeliest error is that the page says "Loading..." forever and shows this error in the console:

Uncaught (in promise) TypeError: Failed to execute 'compile' on 'WebAssembly': Incorrect response MIME type. Expected 'application/wasm'.

You'll need your webserver to send a Content-Type: application/wasm header in its response to requests for .wasm files. For Apache it's enough to add this to your .htaccess:

AddType application/wasm .wasm