DocSmith

AI documentation engineer for GitHub repositories.

Quickstart · Why DocSmith · How it works · Document types · CLI · Providers

The problem

Ask a general-purpose model to write documentation for a repository and it will confidently invent install commands, file paths, endpoints, and features. The prose sounds right. The details are often wrong.

DocSmith is built around one rule: the model may only state what the repository evidence supports. It analyzes the repository, builds a small evidence brief, writes from that brief, then reviews the result against the same evidence and rewrites unsupported claims.

What the output looks like

A real excerpt from a live run against ilyaskhan12Q/edugov-portal — 82/100, zero review issues:

## Features

*   **API Endpoints**:
    *   Admissions management (`supabase/functions/api-v1-admissions/index.ts`)
    *   Grievances and feedback handling (`supabase/functions/api-v1-grievances/index.ts`)
    *   Notices and announcements distribution (`supabase/functions/api-v1-notices/index.ts`)
    *   Public results search by roll number and date of birth (`supabase/functions/api-v1-results/index.ts`)
    *   Health check for API and database status (`supabase/functions/api-v1-health/index.ts`)
    *   Staff management (`supabase/functions/api-v1-staff/index.ts`)
*   **Core Utilities**:
    *   Shared configuration and CORS handling (`supabase/functions/_shared/index.ts`)
    *   Database interaction with admin and user clients, authentication, and role checking (`supabase/functions/_shared/index.ts`)
    *   Comprehensive error handling and logging (`supabase/functions/_shared/index.ts`)
    *   Request validation and response helpers (`supabase/functions/_shared/index.ts`)
*   **Technology Stack**:
    *   Developed with TypeScript and React
    *   Utilizes Supabase for backend services
    *   Styled using Tailwind CSS
    *   Includes UI components from Radix UI
    *   Manages forms with React Hook Form
    *   Uses TanStack Query for data fetching

Every path and package above was detected in the repository, not guessed.

Quickstart

1. Install

The PyPI package is docsmith-ai (the docsmith name is already taken). Python 3.10+ is required.

# pip
pip install "docsmith-ai[gemini]"

# uvx — run without installing
uvx --from "docsmith-ai[gemini]" docsmith generate owner/repo

# pipx
pipx install "docsmith-ai[gemini]"

Swap gemini for openai, anthropic, mistral, or all-providers.

2. Configure

docsmith config

The setup wizard selects a provider, stores your API key in ~/.docsmith/config.json (written with 0600 permissions), and can save a GitHub token. Re-running it merges new settings into the existing file, so keys for other providers and your preferences are preserved. A token is optional, but it raises the GitHub API limit from 60 to 5,000 requests per hour and is required for private repositories.

Headless / CI configuration

Every setting can come from the environment, so a config file is not required:

export DOCSMITH_PROVIDER=gemini
export DOCSMITH_GEMINI_API_KEY="..."
export DOCSMITH_GITHUB_TOKEN="..."   # optional; GITHUB_TOKEN also works

docsmith generate owner/repo --quick -o docs

Supported keys are DOCSMITH_GEMINI_API_KEY, DOCSMITH_OPENAI_API_KEY, DOCSMITH_ANTHROPIC_API_KEY, and DOCSMITH_MISTRAL_API_KEY. Conventional names (GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, MISTRAL_API_KEY) also work. DOCSMITH_MODEL overrides the model, and DOCSMITH_DEBUG=1 prints full tracebacks.

Environment keys are never written to disk. Without a terminal, DocSmith exits with an actionable error instead of waiting on a prompt — use --quick in CI.

3. Generate

# Full interactive flow: choose documents, audience, and tone
docsmith generate https://github.com/owner/repo

# Skip the questionnaire (README, CONTRIBUTING, ARCHITECTURE)
docsmith generate owner/repo --quick

# Print to the terminal instead of writing files
docsmith generate owner/repo --preview

# Custom output directory
docsmith generate owner/repo -o ./docs

Generated files are written to docsmith-output/ by default, or to the output_dir in your config.

What makes it different

Evidence, not a raw repo dump

docsmith/generation/evidence.py builds a deterministic, bounded brief from the analysis pipeline:

• Repository facts, real URLs, license, and project signals
• File layout and the files whose contents were inspected
• Dependencies with versions, split into runtime and development
• Real classes, function signatures, HTTP endpoints, CLI commands, and env var names
• Commands already documented in the existing README
• Source excerpts ranked by document type
• Recent commits for changelogs

The brief is capped at roughly 16k characters. Real .env files are never fetched, credentials are redacted, and placeholder commands such as <YOUR_GIT_URL> are filtered before the model sees them.

It verifies claims

The reviewer checks generated shell commands against the detected dependency set, file paths against the repository tree, documented endpoints against detected routes, and rejects placeholder values. Issues become actionable review results instead of shipping silently.

It fixes itself

When review finds a refinable issue, the refiner receives the same evidence and is instructed to delete unsupported claims rather than invent replacements. The document is then re-reviewed and re-scored before output.

How it works

Document types

Analysis capabilities

• Languages — Python, JavaScript, TypeScript, Go, Rust, Java, C#, C++, Ruby, PHP, Swift, Kotlin
• Frameworks — FastAPI, Flask, Django, Express, Next.js, React, Vue, Angular, Spring, Rails, Laravel, Gin, Actix, Typer, Click
• Dependencies — requirements.txt, pyproject.toml (PEP 621, Poetry, dependency groups), package.json, Cargo.toml, go.mod
• API routes — FastAPI, Flask, Django, Express
• CLI commands — Typer and Click, including arguments and options
• Code intelligence — Public classes, methods, function signatures, and docstrings
• Environment variables — From source and .env.example / .env.sample / .env.template files (never a real .env)

Quality scoring

Every document is scored on five weighted dimensions:

AI providers

Switch providers at any time with docsmith config (existing settings are preserved) or by setting DOCSMITH_PROVIDER. All provider calls go through a single interface with retry and backoff for transient failures.

CLI reference

docsmith generate <owner/repo | url> [--output DIR] [--preview] [--quick] [--skip-review]
docsmith analyze  <owner/repo | url>
docsmith config
docsmith cache clear
docsmith version

generate flags:

python -m docsmith works as an alternative entry point. Interactive prompts are only shown in a terminal; in CI, use --quick plus environment variables.

Project structure

docsmith/
├── ai/
│   ├── providers/          # Gemini, OpenAI, Anthropic, Mistral
│   ├── prompts/            # 8 Jinja2 prompt templates
│   └── orchestrator.py     # Provider factory + retry policy
├── analysis/
│   ├── analyzer.py         # Analysis orchestrator
│   ├── architecture_builder.py
│   ├── cli_detector.py
│   ├── dependency_detector.py
│   ├── framework_detector.py
│   └── route_detector.py
├── config/                 # Settings + atomic, owner-only storage
├── generation/
│   ├── evidence.py         # Bounded, redacted evidence brief
│   ├── planner.py          # Document structure plans
│   ├── writer.py           # Prompt assembly + generation
│   ├── reviewer.py         # Claim and structure checks
│   ├── refiner.py          # Evidence-grounded fixes
│   └── scorer.py           # Weighted quality score
├── github/
│   ├── fetcher.py          # Retrying API client + file selection
│   ├── parser.py
│   └── repository_context.py
├── models/                 # Pydantic models
├── output/                 # Files, preview, and summary report
├── main.py                 # Typer CLI
└── __main__.py             # python -m docsmith

FAQ

Does DocSmith send my entire repository to an LLM? No. Only the evidence brief is sent. It is selected, capped at roughly 16k characters, redacted, and excludes real .env files.

Does it work with private repositories? Yes, with a GitHub token that has access to the repository. Add it during docsmith config, or set DOCSMITH_GITHUB_TOKEN.

Can I use it in CI? Yes. Set DOCSMITH_PROVIDER and the matching DOCSMITH_*_API_KEY (plus DOCSMITH_GITHUB_TOKEN for private repositories) and run with --quick. No config file or terminal is required. A dedicated GitHub Action is on the roadmap.

What if I disagree with the generated content? Every document is plain Markdown in docsmith-output/. Edit it like any other file, or regenerate with a different provider, model, tone, or audience.

Development

git clone https://github.com/ilyaskhan12Q/DocSmith.git
cd DocSmith

python -m venv .venv
source .venv/bin/activate

pip install -e ".[dev,all-providers]"

# Tests
pytest -v
pytest --cov=docsmith --cov-report=term-missing

# Lint and format
ruff check .
ruff format .

Roadmap

• Local repository analysis without GitHub
• Parallel document generation
• Custom user-defined prompt templates
• First-party GitHub Action for doc updates
• Diff mode against existing documentation
• Documentation output in multiple languages
• Plugin system for custom analyzers and generators

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup and workflow, and open an issue for bugs or feature requests.

1. Fork the repository
2. Create a feature branch (git checkout -b feat/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push the branch (git push origin feat/amazing-feature)
5. Open a Pull Request

License

MIT — see LICENSE for details.