Docs Phase 1: Decide generated API docs strategy

[MichaelFisher1997]

Parent: #609

Summary

Decide the technical approach for generated Zig API documentation before building a full pipeline.

Options To Evaluate

• Zig's built-in autodoc output.
• A custom std.zig.Ast extractor.
• A hybrid approach where Zig/build output is post-processed for the docs site.

Acceptance Criteria

• Document the recommended approach and why.
• Identify what data the docs site needs: MDX, static HTML, JSON, or another artifact.
• Call out major risks, including cross-module references, generic types, comments attached to declarations, and Docusaurus compatibility.
• Recommend whether a custom tools/docgen.zig is justified.

[github-actions]

This is a Feature Request / Planning Decision — not a bug. It asks for an architectural decision on API docs generation strategy.

Analysis:

The codebase currently has no documentation pipeline. The 20+ engine-* and world-* modules use Zig's package-based structure with root.zig re-exports. Key considerations:

Option 1: Zig built-in autodoc

• zig build --doc outputs HTML/sitemap to zig-out/doc/
• Works out-of-the-box but output format and Docusaurus compatibility require post-processing
• Generic types and cross-module links render but may need cleanup

Option 2: Custom std.zig.Ast extractor

• Full control over artifact format (JSON/MDX for Docusaurus)
• Significant effort to maintain; Zig AST APIs change between releases
• Could handle project-specific comment conventions and cross-module reference rewriting

Option 3: Hybrid (Zig output + post-processing)

• Use zig build --doc as the primary extractor, then transform to desired format
• Lower implementation cost; risk is output format drift if Zig changes autodoc

Major risks to call out:

• Cross-module @import references need rewriting for static HTML/export
• Generic types (comptime parameters) render differently across tools
• Doc comments (//!, ///) attached to declarations must be preserved accurately
• Docusaurus MDX support would require a transformation layer regardless of approach

Recommendation:
A custom tools/docgen.zig is not justified for initial scope. The hybrid approach (Zig autodoc → post-process) minimizes initial investment. A custom tool becomes worthwhile only if the project needs strict comment formatting enforcement or custom metadata that autodoc doesn't expose.

Suggested sub-tasks if this is approved:

1. Evaluate zig build --doc output for this codebase's module layout
2. Prototype a Docusaurus-compatible JSON/MDX transform for the autodoc output
3. Evaluate cross-module link rewriting needs
4. Document artifact format decision (MDX vs static HTML vs JSON)

opencode session  |  github run

[github-actions]

This issue has had no activity for 60 days. It will be closed in 14 days unless there is new activity or an exemption label is added.

[github-actions]

Closing this issue because it remained stale for 14 days without new activity.