Docs: Build a maintainable generated API documentation pipeline

[MichaelFisher1997]

Summary

Replace the stale one-shot MDX generator proposal with a phased documentation pipeline that matches ZigCraft's current module-based architecture.

Context

The previous proposal in #207 targeted src/ and attempted to solve AST parsing, MDX output, Docusaurus structure, sidebar generation, and CI artifacts in one pass. The codebase now primarily exposes engine and world APIs through modules/*/src/root.zig, and the default branch/workflow target is dev.

Goals

• Decide the generated docs strategy before committing to a full custom generator.
• Scope generated API docs around public module exports, especially modules/*/src/root.zig.
• Prototype against a small set of representative modules before adding CI.
• Keep Docusaurus integration and artifact publishing as later steps once output format is stable.

Proposed Phases

1. Compare Zig autodoc, custom std.zig.Ast extraction, and hybrid approaches.
2. Define what counts as public API documentation for this repo.
3. Prototype a minimal module API extractor for a few representative modules.
4. Establish doc-comment standards for module and declaration docs.
5. Add CI artifact generation targeting dev after the prototype is useful.
6. Integrate the generated output into the Docusaurus/docs site.

Notes

This supersedes #207 rather than continuing from the abandoned #208 implementation.

[github-actions]

This is a Feature Request (not a bug).

The proposal is well-scoped and follows a sound phased approach. The key improvements over #207:

• Targets modules/*/src/root.zig directly instead of parsing src/
• Starts with comparison of extraction approaches before committing to a generator
• Prototypes before CI integration

Analysis:

• The phased structure (compare → define → prototype → standards → CI → Docusaurus) naturally breaks this into manageable sub-tasks
• No need to further split this issue
• The "prototype against a small set of representative modules" gate before adding CI is a good risk mitigation strategy

Suggestion: Phase 1 should explicitly include engine-core and world-core as the representative modules for prototyping—they already have well-structured root.zig exports and represent the two primary API surfaces (engine vs world). This gives early signal on whether Zig's built-in autodoc suffices or if custom AST extraction is needed.

No code changes needed—this is a documentation architecture proposal that can proceed as outlined.

opencode session  |  github run