Metadata-Version: 2.5
Name: docsmith-ai
Version: 0.2.1
Summary: AI-powered documentation engineer that analyzes GitHub repos and generates production-ready docs.
Project-URL: Homepage, https://github.com/ilyaskhan12Q/DocSmith
Project-URL: Documentation, https://github.com/ilyaskhan12Q/DocSmith#readme
Project-URL: Repository, https://github.com/ilyaskhan12Q/DocSmith
Project-URL: Issues, https://github.com/ilyaskhan12Q/DocSmith/issues
Project-URL: Changelog, https://github.com/ilyaskhan12Q/DocSmith/blob/main/CHANGELOG.md
Author: DocSmith Contributors
License-Expression: MIT
License-File: LICENSE
Keywords: ai,cli,developer-tools,documentation,generator,github,llm,readme
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: jinja2>=3.1.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyperclip>=1.8.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.9.0
Provides-Extra: all-providers
Requires-Dist: anthropic>=0.20.0; extra == 'all-providers'
Requires-Dist: google-genai>=1.0.0; extra == 'all-providers'
Requires-Dist: mistralai>=0.1.0; extra == 'all-providers'
Requires-Dist: openai>=1.0.0; extra == 'all-providers'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20.0; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: gemini
Requires-Dist: google-genai>=1.0.0; extra == 'gemini'
Provides-Extra: mistral
Requires-Dist: mistralai>=0.1.0; extra == 'mistral'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Description-Content-Type: text/markdown

<div align="center">

<img src="https://raw.githubusercontent.com/ilyaskhan12Q/DocSmith/main/assets/banner.svg" alt="DocSmith — documentation that reads your code first" width="100%">

# DocSmith

**AI documentation engineer for GitHub repositories.**

[![PyPI](https://img.shields.io/pypi/v/docsmith-ai?style=flat-square&label=pypi&color=2563eb)](https://pypi.org/project/docsmith-ai/)
[![Python](https://img.shields.io/pypi/pyversions/docsmith-ai?style=flat-square)](https://pypi.org/project/docsmith-ai/)
[![CI](https://github.com/ilyaskhan12Q/DocSmith/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ilyaskhan12Q/DocSmith/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-22c55e?style=flat-square)](https://github.com/ilyaskhan12Q/DocSmith/blob/main/LICENSE)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json&style=flat-square)](https://github.com/astral-sh/ruff)
[![PRs welcome](https://img.shields.io/badge/PRs-welcome-8b5cf6?style=flat-square)](https://github.com/ilyaskhan12Q/DocSmith/pulls)

[Quickstart](#quickstart) · [Why DocSmith](#what-makes-it-different) · [How it works](#how-it-works) · [Document types](#document-types) · [CLI](#cli-reference) · [Providers](#ai-providers)

</div>

---

## 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.

| | General-purpose LLM | DocSmith |
|---|---|---|
| **Input** | Whatever you paste, or a raw repo dump | Bounded, redacted evidence brief |
| **Install commands** | Guessed | Derived from manifests and existing docs |
| **File paths** | Often invented | Checked against the real tree |
| **Endpoints & CLI** | Plausible fiction | Detected from source |
| **Self-check** | None | Reviewer + automatic refinement |
| **Output** | One document | 8 document types, scored 0–100 |

## What the output looks like

A real excerpt from a live run against [`ilyaskhan12Q/edugov-portal`](https://github.com/ilyaskhan12Q/edugov-portal) — **82/100, zero review issues**:

```markdown
## 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.

```bash
# 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

```bash
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:

```bash
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

```bash
# 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

<div align="center">
<img src="https://raw.githubusercontent.com/ilyaskhan12Q/DocSmith/main/assets/pipeline.svg" alt="Pipeline: GitHub → Analyzer → Evidence → Writer → Reviewer → Output" width="100%">
</div>

| Stage | Responsibility |
|---|---|
| **Fetcher** | GitHub API with retries, backoff, and intelligent file selection |
| **Analyzer** | Languages, frameworks, dependencies, routes, CLI, classes, functions, env vars |
| **RepoContext** | Validated Pydantic model of the repository |
| **Evidence** | Bounded, redacted, document-specific brief |
| **Planner** | Chooses sections based on what was actually detected |
| **Writer** | Jinja2 prompt template + AI provider |
| **Reviewer** | Placeholder, command, path, endpoint, and section checks |
| **Refiner** | Fixes refinable issues using the same evidence |
| **Scorer** | Weighted 0–100 quality score |
| **Output** | Markdown files, terminal preview, and a report table |

## Document types

| Document | What grounds it |
|---|---|
| `README.md` | Facts, dependencies, entry points, CLI/endpoints, existing README |
| `CONTRIBUTING.md` | Package manager, test/CI config, existing README |
| `SECURITY.md` | Repository URL, license, version signals |
| `ARCHITECTURE.md` | Code map, source excerpts, dependencies |
| `API_REFERENCE.md` | Endpoints, CLI commands, classes, functions |
| `CHANGELOG.md` | Recent commit history |
| `DEVELOPMENT_GUIDE.md` | Entry points, tests, CI, environment variables |
| `QUICKSTART.md` | Install commands, entry points, CLI |

## 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:

| Dimension | Weight | What it measures |
|---|---|---|
| Correctness | 30% | References real repository content |
| Completeness | 25% | Covers the planned sections |
| Usability | 20% | Structure, readability, links |
| Examples | 15% | Useful, grounded code examples |
| Maintainability | 10% | Ease of keeping the document current |

## AI providers

| Provider | Default model | Install extra |
|---|---|---|
| Google Gemini | `gemini-2.5-flash` | `docsmith-ai[gemini]` |
| OpenAI | `gpt-4o` | `docsmith-ai[openai]` |
| Anthropic | `claude-sonnet-4-20250514` | `docsmith-ai[anthropic]` |
| Mistral AI | `mistral-large-latest` | `docsmith-ai[mistral]` |

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

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

| Command | Description |
|---|---|
| `generate` | Analyze a repository and generate documentation |
| `analyze` | Print the repository intelligence table without generating |
| `config` | Run the setup wizard and merge provider/token settings |
| `cache clear` | Remove cached repository analyses |
| `version` | Print the installed version |

`generate` flags:

| Flag | Effect |
|---|---|
| `-o, --output DIR` | Output directory (default: `docsmith-output`, or `output_dir` from config) |
| `-p, --preview` | Print documents to the terminal instead of writing files |
| `-q, --quick` | Skip the questionnaire and use README, CONTRIBUTING, ARCHITECTURE |
| `--skip-review` | Skip the review/refine/score pass |

`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

```text
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

```bash
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](https://github.com/ilyaskhan12Q/DocSmith/blob/main/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](https://github.com/ilyaskhan12Q/DocSmith/blob/main/LICENSE) for details.

---

<div align="center">

**Built for developers who would rather ship code than write docs.**

[Back to top](#docsmith)

</div>
