Zigdoc: zig docs in your terminal

Showcase
1

Tired of explaining to my agent how to get zig stdlib documentation, I decided to create a tool to mimic how zig generates html docs. I call it zigdoc. It does a couple of special things:

  1. It is version aware. It’ll run zig version before doing anything, because it will also run zig env to find the stdlib directory. In 0.14 this is in json, in 0.15 its zon…thus we must know the version.
  2. It is LLM friendly. Output is intentionally sparse. You are intended to keep calling zigdoc with ever growing accessors to explore the public API. It gives an LLM all of the public api, the symbol signature, and location to source file on disc + line number - agents can do pretty much anything with that info.
  3. It is import friendly. zigdoc runs a custom build runner when it detects a build.zig in the current working directory. That build runner is also version aware. It spits out a json dump of ALL module import names and resolved paths. From there, it indexes the root and any imported file for all public api. This way, you can get generated documentation for any module your project imports.

Say I’m making a project and have imported zeit. But I don’t know how to use it

$ zigdoc zeit
Symbol: zeit
Location: /Users/tim/.cache/zig/p/zeit-0.6.0-5I6bk4t8AgCP0UGGHVF_khlmWZkAF5XtfQWEKCyLoptU/src/zeit.zig:1Category: namespace
Type: namespace (file root)

Types:
  timezone
  TimeZone
  Location
  Instant
  Month
  Duration
  Weekday
  Date
  TimeComparison
  Time

Functions:
  local
  loadTimeZone
  instant
  daysSinceEpoch
  isLeapYear
  weekdayFromDays
  civilFromDays
  daysFromCivil

Constants:
  utc

Oh, I wonder what that Date type is?

$ zigdoc zeit.Date
Symbol: zeit.Date
Location: /Users/tim/.cache/zig/p/zeit-0.6.0-5I6bk4t8AgCP0UGGHVF_khlmWZkAF5XtfQWEKCyLoptU/src/zeit.zig:479
Category: container
Type: struct

Documentation:

Fields:
  year: i32
  month: Month
  day: u5

Functions:
  eql
  compare
21 Likes
2

This is really nice. I’ve wanted something like that because I really don’t like the official docs.

Can one use it to explore the api of any zig module/library?

3

Nice! Making it text file based makes it grepable. It’s easy to integrate with MCP.

4

Yep! As long as you have imported it in your build.zig you can do arbitrary libraries. Here’s an example output from the Ghostty repo, which uses uucode

$ zigdoc uucode
Symbol: uucode
Location: /Users/tim/.cache/zig/p/uucode-0.1.0-ZZjBPjQHQADuCy1VMWftjrMl3iWqgMpUugWVQJG6_7xT/src/root.zig:1
Category: namespace
Type: namespace (file root)

Type Functions:
  TypeOf
  TypeOfAll

Types:
  config
  types
  ascii
  grapheme
  utf8
  x

Functions:
  get
  getAll

Constants:
  FieldEnum
5

Why would you connect it to MCP? It can be used directly has a command line tool

2 Likes
6

To provide better context to a LLM so that it can write code using an unknown API.

7

Have you tested it in windows? I couldn’t make it work, getting SyntaxError for third party libraries, in example clap that’s imported and in build.zig, or FileNotFound for std libraries, like Std.ArrayList in example. I don’t know if i’m missing something or doing something wrong.

8

I haven’t tried it on windows, that seems strange it wouldn’t work there.