A "just-enough-functionality" Zig docs server: zds

Showcase
1

zds comes in at just 70k in ReleaseSmall on my m1 mac. It’s hardcoded to just serve the Zig autodoc files in the current working directory. Thre’s a sample project in the sample directory with a build.zig that shows one possible way of using this.

The relevant code in that sample build.zig:

    const docs_wf = b.addWriteFiles();
    _ = docs_wf.addCopyDirectory(exe.getEmittedDocs(), "docs", .{});

    const zds_wf = b.addWriteFiles();
    const zds_src = zds_wf.add("zds.zig",
        \\const std = @import("std");
        \\
        \\pub fn main() !void {
        \\    try @import("zds").zds("127.0.0.1", 8080, 6);
        \\}
    );

    const zds = b.dependency("zds", .{});

    const docs_server = b.addExecutable(.{
        .name = "zds",
        .root_source_file = zds_src,
        .target = b.host,
        .optimize = .ReleaseSmall,
    });
    docs_server.root_module.addImport("zds", zds.module("zds"));

    _ = docs_wf.addCopyFile(docs_server.getEmittedBin(), "docs/zds");

    const install_docs = b.addInstallDirectory(.{
        .source_dir = docs_wf.getDirectory(),
        .install_dir = .prefix,
        .install_subdir = ".",
    });

    const docs_opt = b.option(bool, "docs", "Generate and install docs.") orelse false;
    if (docs_opt) b.getInstallStep().dependOn(&install_docs.step);

Then

$ cd zig-out/docs && ./zds

and point your browser to http://localhost:8080/.

10 Likes
Documents generated by local access report CORS error
Simple http file server
2

There is already a server in zig (zig std), so why is a new one needed?

3

This post is a couple years old now. If memory serves, this was around the time that the ability to run a local server was introduced, but I would definitely need to check the history books to state that with any certainty.

1 Like
4

So that you can run a server that shows the docs you wrote for your own library.

zig std only shows the docs of the standard library not custom docs you have written for your own projects, but I think it would be good if zig std could evolve to become a more unified zig docs that can show all locally available docs.

1 Like
5

Use getEmittedDocs and python -m http.server 8000 -d ./zig-out/path/to/docs/.