# Documentation System

[← Script Management](Script-Management.md) | [Home](Home.md) | [Team Workflows →](Team-Workflows.md)

---

## Table of Contents

- [Overview](#overview)
- [Inline Documentation](#inline-documentation)
- [Markdown Documentation](#markdown-documentation)
- [Documentation Commands](#documentation-commands)
- [Best Practices](#best-practices)
- [Examples](#examples)
- [Next Steps](#next-steps)

## Overview

DotRun features a comprehensive documentation system:

- **Inline Docs**: Embedded documentation in scripts using `### DOC` blocks
- **Markdown Files**: Standalone documentation in the `docs/` directory
- **Auto-rendering**: View formatted docs with `dr help` command
- **Cross-references**: Link between scripts and documentation

## Inline Documentation

### Basic Structure

Every script should include a `### DOC` block:

```bash
#!/usr/bin/env bash
### DOC
# Script Name - Brief Description
#
# Detailed description of what this script does,
# why it exists, and when to use it.
#
# Usage: dr scriptname [options] [arguments]
#
# Options:
#   -h, --help      Show this help message
#   -v, --verbose   Enable verbose output
#
# Arguments:
#   arg1    Description of first argument
#   arg2    Optional second argument
#
# Examples:
#   dr scriptname arg1
#   dr scriptname -v arg1 arg2
### DOC

# Script implementation...
```

### Documentation Sections

#### Required Sections

1. **Script name and brief description**
2. **Usage syntax**
3. **At least one example**

#### Recommended Sections

```bash
### DOC
# Script Name - Brief description
#
# Description:
#   Detailed explanation of the script's purpose
#
# Usage: dr scriptname [options] arguments
#
# Options:
#   -h, --help          Show help
#   -f, --force         Force operation
#   -n, --dry-run       Preview changes
#
# Arguments:
#   input     Input file or directory
#   output    Output location (optional)
#
# Examples:
#   dr scriptname input.txt
#   dr scriptname -f input.txt output.txt
#   dr scriptname --dry-run directory/
#
# Environment Variables:
#   CONFIG_PATH    Path to configuration (default: ~/.config)
#   API_KEY        Required API key for external service
#
# Dependencies:
#   - curl: For API requests
#   - jq: For JSON processing
#
# Exit Codes:
#   0    Success
#   1    General error
#   2    Invalid arguments
#   3    Missing dependencies
#
# Notes:
#   - Requires internet connection
#   - Creates backup before processing
#
# See Also:
#   - dr related-script
#   - Documentation: docs/detailed-guide.md
### DOC
```

### Advanced Documentation

#### Categorization

```bash
### DOC
# Category: deployment
# Subcategory: kubernetes
# Tags: k8s, deploy, production
#
# Deploy to Kubernetes - Production deployment script
# ...
### DOC
```

#### Version Information

```bash
### DOC
# Script: deploy-production
# Version: 2.1.0
# Author: Team Name
# Last Modified: 2024-01-15
#
# Changelog:
#   2.1.0 - Add multi-region support
#   2.0.0 - Breaking: New config format
#   1.0.0 - Initial release
# ...
### DOC
```

#### Complex Examples

```bash
### DOC
# Examples:
#
#   Basic usage:
#     dr deploy-app myapp
#
#   With environment:
#     ENV=staging dr deploy-app myapp
#
#   Full options:
#     dr deploy-app \
#       --environment production \
#       --region us-east-1 \
#       --version 1.2.3 \
#       --rollback-on-failure \
#       myapp
#
#   Using config file:
#     dr deploy-app --config deploy.yml myapp
### DOC
```

## Markdown Documentation

### Creating Documentation

```bash
# Create new documentation
dr doc create getting-started

# Create with category
dr doc create guides/deployment

# Create from template
dr doc create api-guide --template=api-doc
```

### Documentation Structure

```
~/.config/dotrun/docs/
├── README.md              # Main documentation index
├── getting-started.md     # Quick start guide
├── guides/                # Categorized guides
│   ├── deployment.md
│   ├── testing.md
│   └── troubleshooting.md
├── references/            # Reference documentation
│   ├── api.md
│   └── configuration.md
└── examples/              # Example documentation
    ├── basic-workflows.md
    └── advanced-usage.md
```

### Markdown Templates

Create a documentation template:

````markdown
# {{TITLE}}

## Overview

Brief description of the topic.

## Table of Contents

- [Prerequisites](#prerequisites)
- [Getting Started](#getting-started)
- [Configuration](#configuration)
- [Usage](#usage)
- [Examples](#examples)
- [Troubleshooting](#troubleshooting)
- [Related Documentation](#related-documentation)

## Prerequisites

What you need before starting.

## Getting Started

Step-by-step introduction.

## Configuration

Configuration options and setup.

## Usage

Detailed usage instructions.

## Examples

### Example 1: Basic Usage

```bash
# Example command
dr example-script
```
````

### Example 2: Advanced Usage

```bash
# Advanced example
dr example-script --option value
```

## Troubleshooting

Common issues and solutions.

## Related Documentation

- [Related Guide](related-guide.md)
- Script: `dr help scriptname`

````

### Linking Scripts and Docs

Reference documentation from scripts:

```bash
### DOC
# Script Name
#
# Brief description
#
# For detailed information, see:
#   dr doc view deployment-guide
#
# Related documentation:
#   - docs/guides/deployment.md
#   - docs/troubleshooting.md
### DOC
````

Reference scripts from documentation:

```markdown
## Related Scripts

- `dr deploy-staging` - Deploy to staging environment
- `dr deploy-production` - Deploy to production
- `dr rollback` - Rollback deployment

Run `dr help <script>` for detailed usage.
```

## Documentation Commands

### Viewing Documentation

```bash
# View script documentation
dr help scriptname
dr help git/cleanup

# View markdown documentation
dr doc view getting-started
dr doc view guides/deployment

# Open in browser (if glow installed)
dr doc view --browser api-guide
```

### Managing Documentation

```bash
# List all documentation
dr doc list

# Search documentation
dr doc search "deployment"
dr doc search "api" --category guides

# Edit documentation
dr doc edit getting-started

# Remove documentation
dr doc rm outdated-guide
```

### Documentation Index

Generate an index:

```bash
#!/usr/bin/env bash
# generate-doc-index.sh

cat >~/.config/dotrun/docs/README.md <<'EOF'
# DotRun Documentation

## Quick Links

- [Getting Started](getting-started.md)
- [User Guide](guides/user-guide.md)
- [Script Reference](references/scripts.md)

## Documentation by Category

EOF

# Add guides
echo "### Guides" >>~/.config/dotrun/docs/README.md
find ~/.config/dotrun/docs/guides -name "*.md" | sort | while read -r doc; do
  name=$(basename "$doc" .md)
  echo "- [${name^}](guides/$name.md)" >>~/.config/dotrun/docs/README.md
done

# Add references
echo -e "\n### References" >>~/.config/dotrun/docs/README.md
find ~/.config/dotrun/docs/references -name "*.md" | sort | while read -r doc; do
  name=$(basename "$doc" .md)
  echo "- [${name^}](references/$name.md)" >>~/.config/dotrun/docs/README.md
done
```

## Best Practices

### 1. Consistent Format

Use consistent documentation format:

```bash
### DOC
# [CATEGORY/]SCRIPT_NAME - Brief description (one line)
#
# [Empty line]
# Detailed description paragraph.
# Can be multiple lines.
#
# [Empty line]
# Usage: dr scriptname [options] <required> [optional]
#
# [Rest of documentation sections]
### DOC
```

### 2. Clear Examples

Provide realistic examples:

```bash
# Examples:
#   # Deploy to staging with defaults
#   dr deploy staging
#
#   # Deploy specific version to production
#   dr deploy production --version 1.2.3
#
#   # Dry run to see what would happen
#   dr deploy production --dry-run
```

### 3. Dependency Documentation

Always document dependencies:

```bash
# Dependencies:
#   Required:
#     - git: Version control operations
#     - curl: API requests
#   Optional:
#     - jq: JSON pretty printing (falls back to python)
#     - notify-send: Desktop notifications
```

### 4. Error Documentation

Document common errors:

```bash
# Troubleshooting:
#   Error: "API_KEY not set"
#     Solution: Export API_KEY environment variable
#
#   Error: "Connection refused"
#     Solution: Check VPN connection and retry
#
#   Error: "Permission denied"
#     Solution: Run with sudo or check file permissions
```

### 5. Cross-References

Link related resources:

```bash
# See Also:
#   Scripts:
#     - dr deploy-staging (test deployment first)
#     - dr rollback (revert deployment)
#   Documentation:
#     - docs/deployment-guide.md
#     - docs/troubleshooting.md
#   External:
#     - https://example.com/api-docs
```

## Examples

### Complete Script Documentation

```bash
#!/usr/bin/env bash
### DOC
# deploy/production - Deploy application to production
#
# Deploys the application to production environment with
# health checks, rollback capability, and notifications.
#
# Usage: dr deploy/production [options] <version>
#
# Options:
#   -h, --help              Show this help
#   -f, --force             Skip confirmation
#   -n, --dry-run           Preview deployment
#   --no-health-check       Skip health checks
#   --rollback-on-failure   Auto rollback if health check fails
#
# Arguments:
#   version    Version tag to deploy (e.g., v1.2.3)
#
# Examples:
#   # Deploy specific version
#   dr deploy/production v1.2.3
#
#   # Deploy with auto-rollback
#   dr deploy/production --rollback-on-failure v1.2.3
#
#   # Preview deployment
#   dr deploy/production --dry-run v1.2.3
#
# Environment Variables:
#   DEPLOY_KEY       SSH key for deployment (required)
#   SLACK_WEBHOOK    Webhook for notifications (optional)
#   HEALTH_TIMEOUT   Health check timeout in seconds (default: 300)
#
# Dependencies:
#   - ssh: Remote server access
#   - curl: Health checks and notifications
#   - git: Version verification
#
# Exit Codes:
#   0    Deployment successful
#   1    Deployment failed
#   2    Invalid arguments
#   3    Health check failed
#   4    Rollback performed
#
# Notes:
#   - Requires VPN connection to production network
#   - Creates backup before deployment
#   - Logs all actions to ~/.config/dotrun/logs/deploy.log
#
# See Also:
#   - dr deploy/staging (test first)
#   - dr rollback/production
#   - docs/deployment-guide.md
#
# Version: 3.2.1
# Maintainer: Platform Team
# Last Updated: 2024-01-15
### DOC

# Implementation...
```

### Comprehensive Markdown Guide

````markdown
# Deployment Guide

## Overview

This guide covers the complete deployment process for our application,
including staging tests, production deployment, and rollback procedures.

## Table of Contents

- [Prerequisites](#prerequisites)
- [Staging Deployment](#staging-deployment)
- [Production Deployment](#production-deployment)
- [Health Checks](#health-checks)
- [Rollback Procedures](#rollback-procedures)
- [Troubleshooting](#troubleshooting)

## Prerequisites

Before deploying, ensure you have:

1. **Access Requirements**
   - VPN connection to production network
   - SSH key configured (`DEPLOY_KEY`)
   - Deployment permissions in GitHub

2. **Tools Installed**
   - DotRun: `dr --version`
   - Git: `git --version`
   - SSH: `ssh -V`

3. **Environment Variables**
   ```bash
   export DEPLOY_KEY=~/.ssh/deploy_key
   export SLACK_WEBHOOK=https://hooks.slack.com/...
   ```
````

## Staging Deployment

Always test in staging first:

```bash
# Deploy to staging
dr deploy/staging v1.2.3

# Run integration tests
dr test/integration staging

# Check logs
dr logs/staging --tail 100
```

## Production Deployment

### Standard Deployment

```bash
# Deploy specific version
dr deploy/production v1.2.3

# Monitor deployment
dr monitor/deployment production
```

### Advanced Options

```bash
# Deploy with auto-rollback
dr deploy/production \
  --rollback-on-failure \
  --health-timeout 600 \
  v1.2.3

# Blue-green deployment
dr deploy/production \
  --strategy blue-green \
  --switch-timeout 30 \
  v1.2.3
```

## Health Checks

The deployment automatically runs health checks:

1. **HTTP Health**: `/health` endpoint returns 200
2. **Database**: Can connect and query
3. **Dependencies**: All services responding
4. **Performance**: Response time under threshold

Manual health check:

```bash
dr health/production --verbose
```

## Rollback Procedures

### Automatic Rollback

If health checks fail with `--rollback-on-failure`:

1. Deployment reverts automatically
2. Previous version restored
3. Notification sent to Slack
4. Incident logged

### Manual Rollback

```bash
# Rollback to previous version
dr rollback/production

# Rollback to specific version
dr rollback/production v1.2.2

# Emergency rollback (skip checks)
dr rollback/production --emergency
```

## Troubleshooting

### Common Issues

**Deployment Hangs**

```bash
# Check deployment status
dr status/deployment production

# View detailed logs
dr logs/deployment --verbose

# Force cleanup
dr cleanup/deployment production
```

**Health Check Failures**

```bash
# Run detailed health check
dr health/production --debug

# Check specific service
dr health/production --service api
```

**Permission Errors**

```bash
# Verify SSH access
ssh -i $DEPLOY_KEY deploy@prod-server

# Check deployment permissions
dr check/permissions production
```

### Emergency Procedures

In case of critical issues:

1. **Immediate Rollback**

   ```bash
   dr rollback/production --emergency
   ```

2. **Notify Team**

   ```bash
   dr notify/emergency "Production deployment failed"
   ```

3. **Gather Diagnostics**
   ```bash
   dr diagnose/production >incident-report.txt
   ```

## Related Documentation

- [Staging Guide](staging-guide.md)
- [Monitoring Guide](monitoring-guide.md)
- [Incident Response](incident-response.md)

## Related Scripts

- `dr deploy/staging` - Deploy to staging
- `dr deploy/production` - Deploy to production
- `dr rollback/production` - Rollback production
- `dr health/production` - Health checks
- `dr monitor/deployment` - Monitor deployment
- `dr logs/deployment` - View deployment logs

---

For script-specific help, run: `dr help <script-name>`

```

## Next Steps

Master documentation to improve your workflow:

1. **Share Scripts**: Learn [Team Collaboration](Team-Collaboration.md)
2. **Develop Better Scripts**: See [Script Development](Script-Development.md)
3. **Configure Environment**: Read [Configuration Management](Configuration-Management.md)
4. **Improve Workflow**: Explore [Developer Experience](Developer-Experience.md)
5. **Study Examples**: Browse [Example Scripts](Script-Examples.md)

---

[← Script Management](Script-Management.md) | [Team Collaboration →](Team-Collaboration.md) | [Top ↑](#documentation-system)
```