docsfy

Overview of docsfy, what it does, its core workflow (clone → AI plan → AI generate → render HTML), and key features like multi-AI provider support, incremental updates, and beautiful static site output

How to install docsfy via pip/uv from source, Python 3.12+ requirement, installing AI CLI providers (Claude Code, Cursor Agent, Gemini CLI), and setting up environment variables

Generate your first documentation site in minutes — start the server, send a generate request with a GitHub URL, and view the rendered docs

Running docsfy with Docker and docker-compose, multi-stage build details, exposed ports, health checks, data volume persistence, and OpenShift-compatible non-root container setup

All configuration options via environment variables and .env file: AI_PROVIDER, AI_MODEL, AI_CLI_TIMEOUT, LOG_LEVEL, DATA_DIR, and provider-specific keys (ANTHROPIC_API_KEY, GEMINI_API_KEY, etc.)

Supported AI providers (Claude Code, Cursor Agent, Gemini CLI), how to select and configure each one, model selection, timeout tuning, and provider-specific setup including Vertex AI integration

Complete guide to generating documentation: submitting requests via the API, using repo_url vs repo_path, force regeneration, incremental updates via commit SHA tracking, and concurrent page generation

How to serve generated documentation sites via the built-in endpoint at /docs/{project}/{path}, downloading complete sites as tar.gz archives, and the filesystem layout of generated output

Features of the output documentation site: dark/light theme toggle, client-side search with keyboard shortcut (Cmd+K), responsive mobile design, code syntax highlighting, table of contents with scroll spy, copy-to-clipboard, callout boxes, and prev/next navigation

How docsfy generates llms.txt and llms-full.txt files alongside the HTML site for AI consumption, following the llms.txt specification

Overview of the docsfy REST API built with FastAPI, base URL, request/response format, and how background generation works with 202 Accepted responses

POST /api/generate — request body schema (repo_url, repo_path, ai_provider, ai_model, ai_cli_timeout, force), response format, validation rules, and mutual exclusivity of repo_url and repo_path

GET /api/status (list all projects), GET /api/projects/{name} (project details with status, commit SHA, page count), DELETE /api/projects/{name} (remove project and all generated files)

GET /docs/{project}/{path} for serving static HTML, GET /api/projects/{name}/download for tar.gz archive download, and GET /health for health checks

High-level architecture of docsfy: FastAPI web layer, two-phase AI generation pipeline (planning then content), markdown-to-HTML rendering with Jinja2 templates, SQLite storage, and filesystem-based caching

Directory layout and module organization: main.py (API), generator.py (AI orchestration), renderer.py (HTML output), storage.py (SQLite), repository.py (git operations), models.py (Pydantic schemas), config.py (settings), prompts.py (AI prompt templates), and json_parser.py

Deep dive into the two-phase AI workflow: Phase 1 plans documentation structure via AI codebase exploration, Phase 2 generates markdown content for each page concurrently (up to 5 parallel), with caching and incremental update support

SQLite database schema for project metadata, filesystem layout under /data/projects/{name}/ (plan.json, cache/pages/*.md, site/), page-level caching strategy, and path traversal security validation

Setting up the development environment with uv, installing dev dependencies, running the app locally with DEBUG mode, and project tooling overview

Running the test suite with pytest and tox, parallel test execution with pytest-xdist, test structure across 11 modules covering API endpoints, AI generation, rendering, storage, models, and integration tests

Pre-commit hooks configuration: ruff linting/formatting, mypy strict type checking, flake8 with M511 plugin, detect-secrets, gitleaks, and tox unused-code detection