Skip to content

Documentation System

Jump to bottom
Joao Palma edited this page Oct 27, 2025 · 3 revisions

Documentation System

← Script Management | Home | Team Workflows →

Table of Contents

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:

#!/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

### 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

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

Version Information

### 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

### 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

# 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:

# {{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

# Advanced example
dr example-script --option value

Troubleshooting

Common issues and solutions.

Related Documentation


### 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:

## 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

# 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

# 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:

#!/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:

### 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:

# 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:

# 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:

# 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:

# 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

#!/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

# 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:

# 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

# Deploy specific version
dr deploy/production v1.2.3

# Monitor deployment
dr monitor/deployment production

Advanced Options

# 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:

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

# 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

# Check deployment status
dr status/deployment production

# View detailed logs
dr logs/deployment --verbose

# Force cleanup
dr cleanup/deployment production

Health Check Failures

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

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

Permission Errors

# 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

    dr rollback/production --emergency

  2. Notify Team

    dr notify/emergency "Production deployment failed"

  3. Gather Diagnostics

    dr diagnose/production >incident-report.txt

Related Documentation

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)

Clone this wiki locally