sr2

SR2 - Interactive Documentation Tool

Create beautiful, interactive command-line documentation for your projects

SR2 transforms your project documentation into an interactive command-line experience. Instead of static README files, create living documentation that users can navigate, explore, and execute directly.

🎯 Main Features

• 📖 Interactive Documentation: Navigate through structured guides with keyboard controls
• ⚡ Live Command Execution: Execute commands directly from the documentation
• 🎨 Beautiful Interface: Clean, intuitive command-line interface with descriptions
• 🔄 Nested Organization: Create hierarchical documentation structures
• 💬 Rich Descriptions: Add detailed explanations for every command and section
• ⌨️ Interactive Commands: Full support for commands requiring user input
• 🚀 Zero Setup: Just create JSON files and run sr2

Installation

Global Installation (Recommended)

npm i -g sr2

Project Installation

npm i -D sr2

Then add to your package.json scripts:

{
  "scripts": {
    "docs": "sr2"
  }
}

Quick Start

• Create sr2.json and sr2.description.json in your project
• Run sr2 (global) or npm run docs (local) to launch your interactive documentation

What Makes SR2 Special?

Instead of this traditional approach:

README.md:
1. Install dependencies: npm install
2. Run tests: npm test
3. Build project: npm run build

Create this interactive experience:

$ sr2

Use W, A, S, D keys or Arrow keys for navigation
D/→ - go into section, A/← - go back to previous section
W/↑ - previous item, S/↓ - next item
Press Enter to execute command

Install dependencies
Run tests
Build project
Advanced setup
-------------------------------------------
Install dependencies

Install all required packages for the project

Press Enter to execute command

Real-World Examples

Example: Project Setup Guide

sr2.json

{
  "Install dependencies": "npm install",
  "Setup environment": "cp .env.example .env",
  "Run database migrations": "npm run migrate",
  "Start development server": "npm run dev",
  "Run tests": "npm test",
  "Full setup with input": [
    "echo 'Setting up project...'",
    "read -p 'Enter project name: ' name && echo 'Project: $name'",
    "npm install",
    "echo 'Setup complete!'"
  ],
  "Deploy with confirmation": [
    "echo 'Preparing deployment...'",
    "read -p 'Deploy to production? (y/N): ' confirm",
    "if [ \"$confirm\" = \"y\" ]; then npm run deploy:prod; else echo 'Deployment cancelled'; fi"
  ]
}

sr2.description.json

{
  "Install dependencies": "Install all required packages",
  "Setup environment": "Copy environment configuration file",
  "Run database migrations": "Initialize database schema",
  "Start development server": "Launch the development server on port 3000",
  "Run tests": "Execute the test suite",
  "Full setup with input": "Interactive setup with project name input",
  "Deploy with confirmation": "Deploy with user confirmation prompt"
}

Actual terminal output:

$ sr2

Use W, A, S, D keys or Arrow keys for navigation
D/→ - go into section, A/← - go back to previous section
W/↑ - previous item, S/↓ - next item
Press Enter to execute command

Install dependencies
Setup environment
Run database migrations
Start development server
Run tests
Full setup with input
Deploy with confirmation
-------------------------------------------
Full setup with input

Interactive setup with project name input

Press Enter to execute command

$ Setting up project...
Enter project name: MyAwesomeProject
Project: MyAwesomeProject
$ npm install
added 1250 packages in 45s
$ Setup complete!

-------------------------------------------
Press Enter to return to navigation

Example with deployment confirmation:

$ Deploy with confirmation

Deploy with user confirmation prompt

Press Enter to execute command

$ Preparing deployment...
Deploy to production? (y/N): n
Deployment cancelled

-------------------------------------------
Press Enter to return to navigation

1. Nested Documentation Structure

sr2.json

{
  "Quick Start": {
    "Install": "npm install",
    "Setup": "npm run setup",
    "Start": "npm start"
  },
  "Testing": {
    "Unit Tests": "npm run test:unit",
    "Integration Tests": "npm run test:integration",
    "Coverage Report": "npm run test:coverage"
  },
  "Build & Deploy": {
    "Build": "npm run build",
    "Deploy to Staging": "npm run deploy:staging",
    "Deploy to Production": "npm run deploy:prod"
  }
}

sr2.description.json

{
  "Quick Start": {
    "Quick Start": "Get up and running in minutes",
    "Install": "Install all project dependencies",
    "Setup": "Configure environment and database",
    "Start": "Launch the development server"
  },
  "Testing": {
    "Testing": "Comprehensive testing suite",
    "Unit Tests": "Run individual component tests",
    "Integration Tests": "Test component interactions",
    "Coverage Report": "Generate detailed coverage analysis"
  },
  "Build & Deploy": {
    "Build & Deploy": "Production deployment pipeline",
    "Build": "Create optimized production build",
    "Deploy to Staging": "Deploy to staging environment",
    "Deploy to Production": "Deploy to live production"
  }
}

Terminal output when navigating:

$ sr2

Use W, A, S, D keys or Arrow keys for navigation
D/→ - go into section, A/← - go back to previous section
W/↑ - previous item, S/↓ - next item
Press Enter to execute command

Quick Start
Testing
Build & Deploy
-------------------------------------------
Quick Start

Get up and running in minutes

Press Enter to execute command

# User presses D to enter Quick Start section

Quick Start/
Use W, A, S, D keys or Arrow keys for navigation
D/→ - go into section, A/← - go back to previous section
W/↑ - previous item, S/↓ - next item
Press Enter to execute command

Install
Setup
Start
-------------------------------------------
Install

Install all project dependencies

Press Enter to execute command

2. System Administration Guide

sr2.json

{
  "🐧 Linux Setup": {
    "Ubuntu/Debian": {
      "Update System": "sudo apt update && sudo apt upgrade -y",
      "Install Docker": [
        "sudo apt-get remove docker docker-engine docker.io containerd runc",
        "sudo apt-get update",
        "sudo apt-get install ca-certificates curl gnupg",
        "sudo install -m 0755 -d /etc/apt/keyrings",
        "curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg",
        "sudo chmod a+r /etc/apt/keyrings/docker.gpg",
        "echo \"deb [arch=\"$(dpkg --print-architecture)\" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \"$(. /etc/os-release && echo \"$VERSION_CODENAME\")\" stable\" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null",
        "sudo apt-get update",
        "sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin"
      ],
      "Verify Installation": "sudo docker run hello-world"
    },
    "CentOS/RHEL": {
      "Update System": "sudo yum update -y",
      "Install Docker": [
        "sudo yum remove docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-engine",
        "sudo yum install -y yum-utils",
        "sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo",
        "sudo yum install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin"
      ],
      "Start Docker": "sudo systemctl start docker && sudo systemctl enable docker"
    }
  },
  "🐳 Docker Management": {
    "List Containers": "docker ps -a",
    "Clean Up": "docker system prune -a",
    "View Logs": "docker logs <container_name>",
    "Interactive Shell": "docker exec -it <container_name> /bin/bash"
  }
}

3. Interactive Tutorial

sr2.json

{
  "🎓 Learn Git": {
    "📚 Basics": {
      "Initialize Repository": "git init",
      "Check Status": "git status",
      "Add Files": "git add .",
      "First Commit": "git commit -m \"Initial commit\""
    },
    "🌿 Branching": {
      "Create Branch": "git checkout -b feature-branch",
      "Switch Branch": "git checkout main",
      "Merge Branch": "git merge feature-branch",
      "Delete Branch": "git branch -d feature-branch"
    },
    "🔄 Remote Operations": {
      "Add Remote": "git remote add origin <url>",
      "Push Changes": "git push origin main",
      "Pull Changes": "git pull origin main",
      "Clone Repository": "git clone <url>"
    }
  },
  "🛠️ Troubleshooting": {
    "Reset Changes": "git reset --hard HEAD",
    "View History": "git log --oneline",
    "Check Differences": "git diff",
    "Stash Changes": "git stash"
  }
}

Interface Navigation

$ sr2

Use W, A, S, D keys or Arrow keys for navigation
D/→ - go into section, A/← - go back to previous section
W/↑ - previous item, S/↓ - next item
Press Enter to execute command

Install dependencies
Run tests
Build project
Advanced setup
-------------------------------------------
Install dependencies

Install all required packages for the project

Press Enter to execute command

Command Types

Simple Commands

{
  "hello": "echo Hello World"
}

Command Sequences (Arrays)

{
  "setup": [
    "npm install",
    "npm run build",
    "npm start"
  ]
}

Interactive Commands with Input

{
  "user setup": [
    "echo 'Welcome to the setup wizard!'",
    "read -p 'Enter your name: ' name",
    "read -p 'Enter your email: ' email",
    "echo 'Hello $name, your email is $email'",
    "echo 'Setup complete!'"
  ]
}

Conditional Commands

{
  "deploy": [
    "echo 'Checking environment...'",
    "read -p 'Deploy to production? (y/N): ' confirm",
    "if [ \"$confirm\" = \"y\" ]; then",
    "  echo 'Deploying to production...'",
    "  npm run deploy:prod",
    "else",
    "  echo 'Deploying to staging...'",
    "  npm run deploy:staging",
    "fi"
  ]
}

Nested Sections

{
  "development": {
    "start": "npm start",
    "build": "npm run build",
    "test": {
      "unit": "npm run test:unit",
      "integration": "npm run test:integration"
    }
  }
}

Navigation Controls

Key	Action	Description
↑ W	Previous	Move to previous item
↓ S	Next	Move to next item
→ D	Enter	Go into section
← A	Back	Go back to previous section
Enter	Execute	Run selected command

Interactive Commands

SR2 supports commands that require user input:

$ sr2

Use W, A, S, D keys or Arrow keys for navigation
D/→ - go into section, A/← - go back to previous section
W/↑ - previous item, S/↓ - next item
Press Enter to execute command

Setup wizard
Run tests
Build project
-------------------------------------------
Setup wizard

Interactive setup wizard for project configuration

Press Enter to execute command

$ Enter your name: John
Hello, John! Welcome to the project!

-------------------------------------------
Press Enter to return to navigation

Use Cases

📚 Project Documentation

• Onboarding guides for new developers
• Step-by-step setup instructions
• Development workflow documentation

🛠️ System Administration

• Server setup and configuration guides
• Maintenance procedures
• Troubleshooting workflows

🎓 Educational Content

• Interactive tutorials
• Command-line learning tools
• Technical skill development

🚀 DevOps & Deployment

• CI/CD pipeline documentation
• Environment setup guides
• Deployment procedures

File Structure

your-project/
├── sr2.json              # Command structure
├── sr2.description.json  # Descriptions and help text
└── README.md            # Traditional documentation (optional)

Advanced Features

Nested Descriptions

{
  "Section": {
    "Section": "This section's description",
    "Command": "This command's description",
    "Subsection": {
      "Subsection": "Subsection description",
      "Command": "Command description"
    }
  }
}

Command Sequences

{
  "Full Setup": [
    "npm install",
    "npm run setup:env",
    "npm run setup:db",
    "npm start"
  ]
}

Why SR2?

❌ Traditional Documentation Problems

• Static text that gets outdated
• No way to test commands
• Hard to navigate complex procedures
• Users copy-paste commands manually

✅ SR2 Solutions

• Living documentation that stays current
• Direct command execution
• Intuitive navigation
• Interactive experience

Getting Started

Option 1: Global Installation (Recommended)

• Install SR2 globally: npm i -g sr2
• Create your documentation:
  • sr2.json - Command structure
  • sr2.description.json - Descriptions
• Run your documentation: sr2
• Share with your team - They just need to run sr2!

Option 2: Project Installation

• Install SR2 as dev dependency: npm i -D sr2
• Add to package.json scripts:

  {
    "scripts": {
      "docs": "sr2"
    }
  }
  

• Create your documentation files
• Run your documentation: npm run docs
• Team members: npm install && npm run docs

License

MIT License - see LICENSE for details.

Transform your documentation from static text into an interactive experience that users actually want to use!