AutoDoc: Keep Docs in Sync with Your Codebase
NEO built an agent that walks repositories, infers public APIs and behavior, and refreshes Markdown documentation. The goal is less stale README drift and fewer hand-maintained reference pages that fall behind the code.
Problem Statement
We asked NEO to refresh documentation on a schedule or when a pull request lands: summaries, usage examples, and module maps that follow the real source. Manual docs often rot because engineers change code faster than they update prose. AutoDoc treats documentation as a build artifact tied to the same repository state as the code it describes.
Solution Overview
- Repo analysis: Parse packages, entry points, and exports using AST-aware parsing where possible, not only text heuristics.
- Doc synthesis: Generate sections with links back to files and symbols so readers can verify claims in the editor.
- Diff-aware updates: Only regenerate documentation for files that actually changed, which keeps CI fast and diffs reviewable.
- Confidence signals: Each generated section can carry a confidence score so teams know when to treat output as draft versus ready to merge.
What AutoDoc Produces
The agent can maintain several documentation shapes from the same codebase scan:
- README refresh: Project overview, install steps, and quickstart that mirror current scripts and entry points.
- API reference: Per-module or per-package pages listing public functions and classes with signatures inferred from the AST.
- Architecture notes: High-level narrative of how subsystems connect, useful for onboarding when a formal design doc never existed.
Workflow / Pipeline
| Step | Description |
|---|---|
| 1. Scan | Build an AST or symbol index for supported languages; map files to packages |
| 2. Plan | Decide which doc pages need creation or refresh from the change set or full tree |
| 3. Write | Emit Markdown with fenced examples pulled from the repo where appropriate |
| 4. Score | Attach confidence where the model infers behavior that is not explicit in types alone |
| 5. Review | Open a pull request or attach to an existing documentation workflow |
CI and Pull Request Integration
Running AutoDoc in continuous integration turns documentation into a repeatable step. On each push or PR, the agent compares the current tree to the last documented revision, regenerates only affected pages, and opens or updates a branch with doc changes. Teams that require human review still get a clear diff: prose and examples that track the code change that triggered them.
Technical Notes
The reference implementation leans on Python for orchestration, tree-sitter (or similar) for multi-language AST parsing, Jinja2 for templates so output style stays consistent, GitPython for diff-aware runs, and an LLM via OpenRouter for narrative sections that go beyond what a pure parser can extract. Configuration typically covers include and exclude globs, language targets, and how aggressively to rewrite existing Markdown.
Repository & Artifacts
Generated Artifacts:
- Doc generator CLI and templates for README and API-style pages
- Config for include and exclude paths, style preferences, and CI hooks