Guide
Which documentation generator fits the job
"Documentation generator" names three different tools. One reads your code and prints a reference. One reads a prompt and prints prose. One reads your repository, writes documents into it, and checks them before you review. They solve different problems, and most teams need two of them.
Three approaches compared
| Approach | Input | Output | Verified by | Examples |
|---|---|---|---|---|
| From code | Source, OpenAPI | API reference | The compiler | TypeDoc, Sphinx, Swagger UI, Javadoc |
| From a prompt | Pasted text | Prose, images | Nobody | Chat tools |
| Agent in the repo | The codebase | Markdown with typed blocks | Schema check, PR review | Chiltepin |
From code
A reference generator reads the source and prints what it finds: signatures, types, doc comments, routes. It is exact and it runs on every build, so it never drifts. The limit is scope. It describes the parts and says nothing about the whole. It cannot explain why the service exists, how a request crosses three processes, or what to do at 3am when the queue backs up. Keep it for the reference. Do not expect it to write the runbook.
From a prompt
A chat tool writes from what you paste. It is fast and it produces readable prose. It also produces confident errors: a status code that does not exist, a diagram nobody can check, a document with no home. The output is text in a chat window. No schema, no diff, no build step, no reviewer. It is fine for a first draft you will rewrite. It is a poor source of record.
Agent in the repo
This is what Chiltepin does. The agent you already use (Claude Code, Cursor, Codex, Copilot and others) gets an authoring skill with npx skills add jdiejim/chiltepin. It reads the codebase, picks block types that fit the content, writes Markdown with typed YAML blocks, and runs chiltepin check. The renderer draws deterministic SVG and HTML from the data at build time. The model writes data; it never draws. The output is a file in Git with a diff and a reviewer.
What generators get wrong
Every generator that uses a model shares three risks: hallucinated facts, diagrams nobody can verify, and drift once the code changes. Be clear about which of these a tool can address and which it cannot.
chiltepin check enforces strict schemas, resolves every doc#id reference, rejects duplicate ids, and exits non-zero in CI. That catches malformed blocks and broken links between them. It checks structure, not truth. A well-formed endpoint block with the wrong status code passes. Render-by-code addresses the diagram problem: because the picture is drawn from data, the data is what you review. Source-in-Git addresses drift only by proximity: the doc sits beside the code, so the same pull request can change both. The fact check itself still belongs to the reviewer and to an agent that reads the real code before it writes. A generator that claims more than that is overclaiming.
The agent workflow, step by step
The steps block below is one of the block types an agent can write. Its starter template is shown as source and as the rendered result. Nothing on this page is a screenshot.
```steps
title: Deploy a hotfix
items:
- title: Branch from main
body: Hotfixes always branch from the latest main.
code: git checkout -b hotfix/fix-retry main
lang: bash
- title: Ship the fix
body: Commit and push; CI runs the full suite.
code: git push -u origin hotfix/fix-retry
lang: bash
note: CI must be green before the next step.
- title: Tag and deploy
code: git tag v1.4.1 && git push --tags
lang: bash
```The generator workflow itself has six steps:
- Request. "Document the billing service in docs/billing.md."
- The agent reads the code. Routes, models, migrations, config.
- It writes blocks. Endpoint cards, a sequence diagram, an ERD, a decision table, each as fenced YAML in Markdown.
- Check.
chiltepin checkreports errors; the agent fixes them. - Render. Static site, standalone HTML, slides, or PDF from the same source.
- PR review. A person confirms the facts. Structure is already done.
In our own generation eval (40 scenarios, September 2026) an agent with the skill chose the right block 39.5 times out of 40, 33 of 40 documents were clean on first write, 40 of 40 at handoff, with 0 render failures and about 91 seconds per document. The eval is public.
Using both
The practical setup is a reference generator for the parts and an agent for the whole. chiltepin sync joins them: it converts OpenAPI, SQL, DBML, Prisma, and CSV into blocks, so the agent starts from your real schema. chiltepin audit scans a codebase and recommends which documents to write first. Studio is a browser editor for edits that are faster by hand.
The Orders REST API document in the gallery shows what an agent produces for an API: endpoint cards, an ERD, sequence diagrams, an error table. The outage postmortem is the other kind of document, one no reference generator could write. All 40 agent-written documents are at /gallery with their source.
This is docs as code with a schema over the structured parts. For the AI-specific tool category, see the AI documentation generator page. For what "AI docs" should mean to an engineering team, see AI docs.
Frequently asked questions
- What is a documentation generator?
- A tool that produces documentation from some input instead of a blank page. The input decides the category. Reference generators like TypeDoc, Sphinx, and Swagger UI read source code or an OpenAPI file. Chat tools read a prompt. Agent-based tools like Chiltepin read the repository and write documents into it.
- Should I replace TypeDoc or Swagger with an AI generator?
- No. A reference generator is exact for what it covers: every exported symbol, every declared route. Keep it. Use an agent for the documents a reference generator cannot produce: how a request flows through three services, why the team chose a queue over a cron job, what to do when the payment provider is down. With chiltepin sync you can also convert an OpenAPI file into endpoint blocks and build on top of it.
- What is the difference between a chat tool and an agent in the repo?
- A chat tool writes from what you paste and hands the text back. An agent in the repo reads the files itself, writes the document into the codebase, runs the validator, and opens a pull request. The output has a schema, a diff, and a review. The chat output has none of those.
- Does a generator keep documentation in sync with code?
- A reference generator does, because it runs on every build. Prose and diagrams do not sync themselves. Chiltepin narrows the gap by keeping the doc in the same repository as the code and validating it in CI, so a broken reference fails the build. A changed fact still needs a person or an agent to update it.
- Is Chiltepin free?
- Yes. It is MIT-licensed open source. The CLI validates and renders locally, the agent skill installs with npx skills add jdiejim/chiltepin, and there is no hosted service to pay for.