Documentation Generation

aegir docs [options]

Options:
  --publish         Publish to GitHub Pages (default: false)
  --entryPoint      Entry point file for documentation (default: 'src/index.js')
  --message         Commit message for gh-pages branch (default: 'docs: update [skip ci]')
  --user            Git user name for commits (default: 'aegir[bot]')
  --email           Git email for commits (default: 'aegir@users.noreply.github.com')
  --directory       Build directory for documentation (default: 'docs')
  --cname           Custom domain for GitHub Pages (optional)

interface DocsOptions {
  /** Publish to GitHub Pages */
  publish: boolean;
  /** Entry points for TypeDoc documentation */
  entryPoint: string;
  /** Commit message for gh-pages branch */
  message: string;
  /** Git user name for documentation commits */
  user: string;
  /** Git email address for documentation commits */
  email: string;
  /** Output directory for generated documentation */
  directory: string;
  /** Custom domain for GitHub Pages (creates CNAME file) */
  cname?: string;
}

# Generate documentation locally
aegir docs

# Generate and publish to GitHub Pages
aegir docs --publish

# Custom entry point
aegir docs --entryPoint src/api.ts

# Custom output directory
aegir docs --directory ./documentation

# With custom domain
aegir docs --publish --cname api.myproject.com

// .aegir.js
module.exports = {
  docs: {
    publish: true,
    entryPoint: 'src/index.ts',
    directory: 'documentation',
    message: 'docs: update API documentation [skip ci]',
    user: 'docs-bot',
    email: 'docs@myproject.com',
    cname: 'api.myproject.com'
  }
};

// Built-in TypeDoc plugins:
// - typedoc-plugin-mdn-links: Links to MDN documentation
// - typedoc-plugin-mermaid: Mermaid diagram support  
// - typedoc-plugin-missing-exports: Reports missing exports
// - Custom plugins for README integration and symbol resolution

// typedoc.json (optional customization)
{
  "entryPoints": ["src/index.ts"],
  "out": "docs",
  "theme": "default",
  "includeVersion": true,
  "excludePrivate": true,
  "excludeProtected": true,
  "excludeExternals": true,
  "readme": "README.md",
  "name": "My Project API"
}

// Entry point resolution:
// 1. TypeScript projects: src/index.ts or specified --entryPoint
// 2. JavaScript projects: src/index.js or specified --entryPoint  
// 3. Multiple entry points: Can specify directories or multiple files
// 4. Package.json "main" field: Used as fallback if src/index.* not found

# Publishing process:
# 1. Generate documentation in temporary directory
# 2. Create or update gh-pages branch
# 3. Commit documentation with specified message
# 4. Push to GitHub repository
# 5. Configure GitHub Pages settings (if first publish)

// .aegir.js
module.exports = {
  docs: {
    publish: true,
    message: 'docs: update API documentation',
    user: 'GitHub Actions',
    email: 'actions@github.com',
    cname: 'docs.myproject.io' // Custom domain
  }
};

# Custom domain configuration:
# 1. Set --cname option with domain name
# 2. Aegir creates CNAME file in documentation root
# 3. Configure DNS CNAME record pointing to username.github.io
# 4. GitHub Pages automatically uses custom domain

docs/                          # Output directory
├── index.html                # Main documentation page
├── modules/                  # Module documentation
│   ├── index.html           # Module index
│   └── [module-name].html   # Individual modules
├── classes/                 # Class documentation
├── interfaces/              # Interface documentation
├── types/                   # Type alias documentation
├── functions/               # Function documentation
├── variables/               # Variable documentation
├── assets/                  # CSS, JS, and image assets
└── CNAME                    # Custom domain (if configured)

/**
 * @packageDocumentation
 * 
 * This package provides utilities for data processing and validation.
 * 
 * @example
 * ```typescript
 * import { processData } from 'my-package';
 * 
 * const result = await processData(input);
 * ```
 */

/**
 * Process input data with validation and transformation
 * 
 * @param data - Input data to process
 * @param options - Processing options
 * @returns Processed data with metadata
 * 
 * @example
 * ```typescript
 * const result = await processData(
 *   { items: [1, 2, 3] },
 *   { validate: true }
 * );
 * ```
 */
export async function processData(
  data: InputData,
  options: ProcessOptions = {}
): Promise<ProcessResult> {
  // Implementation
}

# GitHub Actions example
name: Documentation

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Generate documentation
        run: npm run docs
      
      - name: Publish to GitHub Pages
        if: github.ref == 'refs/heads/main'
        run: npm run docs -- --publish
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

# Document validation features:
# - TypeScript code example verification
# - Link checking for internal references
# - API completeness checking
# - Missing documentation detection

# Generate docs for specific package
aegir docs --entryPoint packages/core/src/index.ts

# Generate combined documentation
aegir docs --entryPoint packages/*/src/index.ts

/**
 * Best practices enforced:
 * - All public APIs must have documentation
 * - Examples for complex functions
 * - Parameter and return type documentation
 * - @since tags for version tracking
 * - @deprecated tags for deprecated APIs
 * - Package-level documentation in index files
 */