Generating Documentation

Submit a repository to docsfy and get a complete documentation site generated by AI. This guide walks you through starting a generation job from the web dashboard or CLI, picking the right AI provider and branch, and watching the progress in real time.

Prerequisites

  • A running docsfy server (see Getting Started with docsfy)
  • A user account with user or admin role (viewers cannot generate docs)
  • The repository you want to document must be accessible via HTTPS or SSH

Quick Example

From the CLI:

docsfy generate https://github.com/your-org/your-repo

That's it. docsfy clones the repo, plans the documentation structure, generates every page with AI, validates the output, and publishes a browsable site — all from a single command.

Generating via the Web Dashboard

  1. Log in to the docsfy dashboard at your server URL.
  2. Click the + button in the sidebar to open the generation form.
  3. Enter the Repository URL (HTTPS or SSH format).
  4. Choose a Branch (defaults to main). If you've generated docs for this repo before, previously used branches appear as suggestions.
  5. Optionally select a Repository Type — app, library, framework, or tests. Leave it on Auto-detect and docsfy will figure it out.
  6. Pick a Provider and Model from the dropdowns. The server's default provider and model are pre-selected.
  7. Click Generate.

A toast notification confirms that generation has started, and the project immediately appears in the sidebar with a spinning status indicator.

Tip: The form remembers your last repository URL, branch, and repository type across page reloads so you can quickly re-generate after code changes.

Generating via the CLI

Basic Usage

docsfy generate https://github.com/your-org/your-repo

The CLI uses the server defaults for AI provider and model. The output shows the project name, branch, status, and a unique Generation ID you can use to check progress later.

Specifying Branch, Provider, and Model

docsfy generate https://github.com/your-org/your-repo \
  --branch dev \
  --provider claude \
  --model claude-sonnet-4-20250514

Forcing Full Regeneration

By default docsfy performs an incremental update when the documentation already exists — only pages affected by code changes are regenerated. To start from scratch:

docsfy generate https://github.com/your-org/your-repo --force

On the dashboard, check the Force full regeneration checkbox before clicking Generate.

Specifying Repository Type

docsfy generate https://github.com/your-org/your-repo --repo-type library

Valid types are app, tests, library, and framework. Each type produces documentation tailored to the repository's purpose — for example, a library type emphasizes API reference pages, while an app type focuses on usage guides.

Monitoring Progress in Real Time

Dashboard Activity Log

When you select a generating project in the sidebar, the detail panel shows a live Activity Log that tracks every stage:

Stage What's happening
Cloning Fetching the repository from Git
Analyzing Building a knowledge graph of the codebase
Planning AI designs the documentation structure and page list
Generating pages Each page is generated individually — the log shows progress like "Generating page 3 of 12: Authentication"
Validating Checking generated content against the actual codebase
Completeness check Identifying and filling gaps in documentation coverage
Cross-linking Adding links between related pages
Rendering Building the final HTML documentation site

A progress bar shows overall completion, and each stage displays a ✓ when done, a spinner when active, or a circle when pending.

CLI Watch Mode

Add --watch to stream progress directly in your terminal:

docsfy generate https://github.com/your-org/your-repo --watch

The CLI connects via WebSocket and prints stage updates as they happen:

Project: your-repo
Branch: main
Status: generating
Generation ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Watching generation progress...
[generating] cloning
[generating] analyzing
[generating] planning
[generating] generating_pages (3 pages)
[generating] generating_pages (7 pages)
[generating] validating (12 pages)
[generating] cross_linking (12 pages)
[generating] rendering (12 pages)
Generation complete! (12 pages)

Checking Status After the Fact

If you didn't use --watch, check on a generation at any time:

docsfy status your-repo

Or use the Generation ID:

docsfy status a1b2c3d4-e5f6-7890-abcd-ef1234567890

See Managing Projects and Variants for more on inspecting and managing your projects.

Aborting a Generation

Changed your mind? Stop a running generation from the dashboard by clicking the Abort button in the variant detail panel, or from the CLI:

docsfy abort your-repo

To abort a specific variant:

docsfy abort your-repo --branch dev --provider claude --model claude-sonnet-4-20250514

Understanding Variants

Every combination of project name + branch + provider + model creates a distinct variant. You can generate documentation for the same repo with different settings and compare the results.

For example, generating your-repo on main with cursor and again with claude produces two independent documentation sites, each accessible at its own URL:

/docs/your-repo/main/cursor/gpt-5.4-xhigh-fast/
/docs/your-repo/main/claude/claude-sonnet-4-20250514/

See Browsing Generated Documentation for details on navigating and sharing doc URLs.

Advanced Usage

Branch Name Rules

Branch names cannot contain slashes because they appear as a single URL path segment. Use hyphens instead:

✅ Valid ❌ Invalid
release-1.x release/1.x
feature-auth feature/auth
main ../main

Branch names must start with a letter or digit and can contain letters, digits, dots, hyphens, and underscores.

Available Providers and Models

List all available AI providers and their models:

docsfy models

Filter by provider:

docsfy models --provider claude

The server exposes three providers: claude, gemini, and cursor. The available models for each provider are discovered automatically from the configured AI sidecar. See Configuring AI Providers for setup details.

Incremental Updates

When you regenerate documentation for a repo that already has docs, docsfy automatically detects what changed since the last generation. Only affected pages are regenerated, making subsequent runs significantly faster.

The incremental pipeline:

  1. Compares the current commit with the previously documented commit
  2. Identifies which files changed
  3. Determines which documentation pages are affected
  4. Regenerates only those pages while keeping everything else intact

To bypass incremental mode and regenerate everything, use the --force flag.

See Working with Incremental Updates for a deeper look at how change detection works.

Cross-Provider Updates

If you previously generated docs with one provider (e.g., cursor) and now generate with a different provider (e.g., claude), docsfy reuses the existing documentation artifacts as a starting point. The new provider regenerates only what has changed, and the old variant is automatically replaced once the new one is ready.

Concurrent Generation Limits

Each variant (project + branch + provider + model) can only have one active generation at a time. If you try to generate a variant that's already in progress, the server returns a 409 Conflict error. Abort the running generation first, or wait for it to complete.

Note: The server processes multiple page generation requests in parallel (up to 10 by default) to speed up large documentation sites. This is configured server-side and doesn't require any action from you.

Troubleshooting

"Variant is already being generated" Another generation for the same project/branch/provider/model combination is in progress. Use docsfy abort <project> or click Abort in the dashboard, then retry.

"AI sidecar not available" The Pi SDK sidecar service isn't running or isn't reachable. See Configuring AI Providers for sidecar setup.

"Invalid branch name" Branch names cannot contain slashes or start with special characters. Use hyphens instead of slashes (e.g., release-1.x instead of release/1.x).

"Local repo path access requires admin privileges" Only admin users can generate docs from local filesystem paths. Non-admin users must provide a remote repository URL.

Generation stuck or failed Check the Activity Log in the dashboard or run docsfy status <project> for the error message. Common causes include AI provider timeouts, network issues reaching the repository, or invalid repository URLs. You can retry with docsfy generate <url> --force to start fresh.