Generate an API reference from your codebase

Reference docs are the highest-churn, lowest-reward pages you own

An API reference has to be exhaustive to be useful. Every endpoint, every parameter, every response shape, every error code — a reference with gaps sends readers to your support queue, and a reference with inaccuracies sends them somewhere worse.

It's also the part of the documentation that changes most often and rewards the author least. Nobody's promotion packet includes the afternoon they spent updating parameter tables. So the work goes to whoever has the least leverage to refuse it, or it goes undone, and the reference slowly becomes a document people check against the code rather than instead of it.

At which point it isn't doing its job. A reference readers verify is a reference readers don't trust.

Why the obvious fixes fall short

Two approaches dominate, and both stop short of the actual problem.

Docstring generators read annotations and emit a structured dump. This is genuinely accurate about structure and genuinely unpleasant to read — a wall of signatures with no narrative, no orientation, and no sense of which endpoint you actually want. It also inherits whatever the docstrings say, which includes the ones written before the last two refactors.

Maintaining an OpenAPI spec by hand gives you tooling leverage, and teams that do it well get a lot from it. But the spec is a second artifact describing the first one, updated by a person who has to remember to. It drifts for the same reason Markdown drifts. You've moved the problem into YAML, not solved it.

What neither approach does is check whether the documented behaviour is the actual behaviour.

What belongs in a reference — and what doesn't

Before automating anything, it's worth being clear about scope, because a lot of frustration with generated docs comes from expecting them to produce the wrong artifact.

A reference is a lookup surface. Its reader already knows what they want and needs to confirm a detail: the exact parameter name, the shape of the response, which error code means what. They arrive from a search box or a link, take one fact, and leave. Completeness and accuracy are everything; narrative flow is close to irrelevant.

A guide is a learning surface. Its reader doesn't yet know what they need, and the job is sequencing — what to do first, what to ignore for now, what the concepts mean. That requires judgement about a specific audience, and no parser has access to it.

The practical consequence: generation should own the reference completely, and should stay out of the guides. Teams that try to generate their tutorials end up with something technically accurate that teaches nobody anything, then conclude generated documentation doesn't work. Teams that hand-maintain their reference end up with drift. Splitting the doc set along that line — derivable versus not — is what makes the automation worth having. It's also the distinction most tooling blurs, which is why "AI documentation" often means a chat window rather than a reference you can actually navigate.

How Git2Docs generates a reference

It reads the source, not the annotations

Parsing uses tree-sitter across TypeScript, JavaScript, Python, Go, Rust, Java, C, C++, and Ruby, so the reference is built from real syntax — actual signatures, actual types, actual route definitions — rather than from comments that may or may not have kept pace.

It writes prose, not a symbol table

Endpoints get an explanation of what they're for and when you'd reach for them, alongside the parameter tables. This is the part a dump can't do, and it's most of why generated references have historically been treated as a fallback rather than the real documentation.

It executes what it documents

The runtime validator takes documented CLI commands and API calls and runs them against your live deployment. Where the observed response doesn't match the documented one, the mismatch is surfaced and batched into a fix.

This is the claim worth scrutinising, because it's the one that separates a generated reference from a verified one. A copied example that fails is the single fastest way to lose a developer's trust in a doc set. Executing them turns that from a thing you hope about into a thing you check.

It ships a site, not a folder

Output is a hosted documentation site on your own domain with your branding, a support chatbot that answers from the published content with citations back to the source pages, and an MCP endpoint so coding agents can query the reference directly.

What this looks like in practice

1. Connect the repository. Git2Docs reads the branch you point it at.
2. Initial generation. The public surface is parsed and a full reference is written — endpoints, parameters, types, responses, errors — with orienting prose.
3. Validation pass. Documented calls are executed against your live deployment. Mismatches are reported with the observed behaviour alongside the documented claim.
4. Review and edit. Adjust anything that needs a human voice; section-level editing means you're revising a block, not rewriting a page.
5. Publish. The site goes live on your domain, and every subsequent push resyncs it.

When this isn't the right fit