Emitting docs for modules

Help
,
1

Hi all!

I know that we can emit docs for binaries (shared/static libs, exes, objs, etc.).

However, what if we have a zig project that just exports a module but doesn’t produce a binary? Is there any way to emit documentation in this case? Or does the module have to be imported by a binary for the docs to be generated?

Relevant link: Build system tricks

2

The build system just runs the zig binary with some constructed arguments to generate files. There is no zig build-docs command currently, just an -femit-docs flag on build-exe, build-obj, build-lib. A potential work around is to create a library with your module as the root file and only install the emitted documentation, not the binary.

const tlib = b.addStaticLibrary(.{
    .name = "my_lib",
    .root_source_file = .{
        .path = "path/to/module.zig",
    },
    .target = target,
    .optimize = optimize,
});
const docs_step = b.step("docs", "Emit docs");
const docs_install = b.addInstallDirectory(.{
    .install_dir = .prefix,
    .install_subdir = "docs",
    .source_dir = tlib.getEmittedDocs(),
});
docs_step.dependOn(&docs_install.step);

I tried this with a very abstract module I have that doesn’t export any functions (and makes no sense as a static lib) and it seemed to generate documention as expected.

2 Likes
3

Hi, thanks for the reply. That’s good info and a pretty clever trick. The static lib trick worked perfectly. It’s a little hacky but it gets the job done.