Skip to content

Repository-Based Documentation

Generate documentation artifacts from repository analysis. Supports two generation modes: LITE and FULL.

Overview

The smooth docs command analyzes repository structure, code files, and existing documentation to generate structured markdown documentation. The system examines file types, directory structure, and code patterns to produce documentation artifacts.

When to Use It

  • Generate initial README and architecture documentation for new repositories
  • Update documentation after significant code changes
  • Standardize documentation structure across repositories
  • Validate existing documentation coverage

How It Works

  1. The CLI collects repository metadata (file tree, language detection, existing docs)
  2. Repository context is sent to the generation API
  3. The system analyzes code structure and patterns
  4. Documentation artifacts are generated based on the selected mode
  5. Artifacts are returned to the CLI or written to files

Configuration

Required Configuration

Setting Description Required
Authentication JWT token or API key Yes
Repository access Local filesystem or GitHub read access Yes

Optional Configuration

Option Description Default
--full Use FULL mode instead of LITE LITE mode
--write Write artifacts to files Output to stdout
--force Regenerate even if docs exist Skip if fresh
--repo <owner/repo> Target repository Current directory
--output <format> Output format: text or json text

Output Behavior

LITE Mode (Default)

Generates overview documentation:

  • README.md - Repository overview, installation, usage
  • docs/architecture/README.md - High-level architecture summary
smooth docs generate

FULL Mode

Generates comprehensive documentation:

  • All LITE mode artifacts
  • docs/api/README.md - API documentation
  • docs/development/README.md - Development guide
  • Function and method documentation
  • Integration guides
smooth docs generate --full --write

File Output

When --write is specified, artifacts are written to the repository:

repository/
├── README.md
├── CONTRIBUTING.md
└── docs/
    ├── README.md
    ├── architecture/
    │   └── README.md
    └── api/
        └── README.md

Commands

Check Status

smooth docs status

Returns documentation coverage metrics and identifies missing recommended files.

Generate Documentation

smooth docs generate [OPTIONS]

Validate Documentation

smooth docs validate

Checks existing documentation structure against recommended patterns.

Security and Data Handling

Smoothdev encrypts customer data in transit and at rest using tenant-scoped encryption keys. Source data is processed only for the requested operation and is not retained long term. Generated artifacts are returned to the user. Operational metrics and validation logs are retained to improve system reliability and quality.

Limitations

  • Repository size limit: 10,000 files maximum
  • Individual file size limit: 1MB per file
  • Binary files are excluded from analysis
  • Private repositories require appropriate GitHub token permissions
  • Generation time increases with repository size (FULL mode may take several minutes for large repositories)
  • Language support: Python, JavaScript, TypeScript, Go, Java, Rust, C, C++. Other languages have limited analysis.

Troubleshooting

Generation Failures

Error Cause Resolution
Repository not found Invalid path or missing permissions Verify repository path exists and is accessible
Authentication required No valid token Run smooth auth login or set API key
Repository too large Exceeds file count limit Use --repo-path to target a subdirectory
Timeout Large repository in FULL mode Use LITE mode or target specific directories

Output Issues

Issue Cause Resolution
Empty output No analyzable files found Verify repository contains supported file types
Incomplete documentation Analysis limited by file access Check file permissions and .gitignore patterns
Stale documentation Freshness check passed Use --force to regenerate

See Also