mirror of
https://github.com/ivuorinen/gh-action-readme.git
synced 2026-02-14 00:49:28 +00:00
feat: update go version, renovate config, tooling, fixes (#28)
* feat(deps): update go version, renovate config, tooling * chore(deps): update google/go-github to v74 * feat(deps): migrate from yaml.v3 to goccy/go-yaml * chore(deps): update goccy/go-yaml to v1.18.0 and address security concerns * feat: improve issue templates and project configuration - Update GitHub issue templates with CLI-specific fields for better bug reports - Add specialized templates for documentation, theme, and performance issues - Update pre-commit config to include comprehensive documentation linting - Remove outdated Snyk configuration and security references - Update Go version from 1.23+ to 1.24+ across project - Streamline README.md organization and improve clarity - Update CHANGELOG.md and CLAUDE.md formatting - Create comprehensive CONTRIBUTING.md with development guidelines - Remove TODO.md (replaced by docs/roadmap.md) - Move SECURITY.md to docs/security.md * docs: fix markdown linting violations across documentation * fix: resolve template placeholder issues and improve uses statement generation * fix: remove trailing whitespace from GitHub issue template
This commit is contained in:
GitHub
30
docs/README.md
Normal file
30
docs/README.md
Normal file
@@ -0,0 +1,30 @@
|
||||
# Documentation
|
||||
|
||||
Welcome to the gh-action-readme documentation! This directory contains comprehensive guides for using and developing the tool.
|
||||
|
||||
## 📖 User Documentation
|
||||
|
||||
- **[Installation](installation.md)** - Installation methods and package managers
|
||||
- **[Usage](usage.md)** - Comprehensive usage examples and CLI reference
|
||||
- **[Configuration](configuration.md)** - Config files, environment variables, and settings
|
||||
- **[Themes](themes.md)** - Available themes, customization, and examples
|
||||
|
||||
## 🔧 Developer Documentation
|
||||
|
||||
- **[Development](development.md)** - Development setup, testing, and contribution guide
|
||||
- **[Security](security.md)** - Security practices, vulnerability reporting, and policies
|
||||
- **[API Reference](api.md)** - Detailed CLI command reference
|
||||
|
||||
## 🚀 Project Information
|
||||
|
||||
- **[Roadmap](roadmap.md)** - Future plans and strategic initiatives
|
||||
|
||||
## 🤝 Getting Help
|
||||
|
||||
- Check the relevant documentation section above
|
||||
- Browse the [GitHub Issues](https://github.com/ivuorinen/gh-action-readme/issues)
|
||||
- See the main [README.md](../README.md) for quick start information
|
||||
|
||||
---
|
||||
|
||||
For the latest updates and announcements, see the [CHANGELOG.md](../CHANGELOG.md).
|
||||
507
docs/api.md
Normal file
507
docs/api.md
Normal file
@@ -0,0 +1,507 @@
|
||||
# API Reference
|
||||
|
||||
Complete command-line interface reference for gh-action-readme.
|
||||
|
||||
## 📋 Command Overview
|
||||
|
||||
```bash
|
||||
gh-action-readme [command] [flags]
|
||||
```
|
||||
|
||||
### Available Commands
|
||||
|
||||
- **`gen`** - Generate documentation from action.yml files
|
||||
- **`validate`** - Validate action.yml files with suggestions
|
||||
- **`config`** - Configuration management commands
|
||||
- **`version`** - Show version information
|
||||
- **`help`** - Help about any command
|
||||
|
||||
## 🚀 Generation Command
|
||||
|
||||
### Basic Syntax
|
||||
|
||||
```bash
|
||||
gh-action-readme gen [directory_or_file] [flags]
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
- **`[directory_or_file]`** - Optional path to action.yml file or directory containing one
|
||||
- If omitted, searches current directory for `action.yml` or `action.yaml`
|
||||
- Supports both files and directories
|
||||
- Examples: `action.yml`, `./actions/checkout/`, `/path/to/action/`
|
||||
|
||||
### Flags
|
||||
|
||||
#### Output Options
|
||||
|
||||
| Flag | Short | Type | Default | Description |
|
||||
|------|-------|------|---------|-------------|
|
||||
| `--output-format` | `-f` | string | `md` | Output format: md, html, json, asciidoc |
|
||||
| `--output-dir` | `-o` | string | `.` | Output directory for generated files |
|
||||
| `--output` | | string | | Custom output filename (overrides default naming) |
|
||||
|
||||
#### Theme Options
|
||||
|
||||
| Flag | Short | Type | Default | Description |
|
||||
|------|-------|------|---------|-------------|
|
||||
| `--theme` | `-t` | string | `default` | Theme: github, gitlab, minimal, professional, default |
|
||||
|
||||
#### Processing Options
|
||||
|
||||
| Flag | Short | Type | Default | Description |
|
||||
|------|-------|------|---------|-------------|
|
||||
| `--recursive` | `-r` | boolean | `false` | Search directories recursively for action.yml files |
|
||||
| `--quiet` | `-q` | boolean | `false` | Suppress progress output |
|
||||
| `--verbose` | `-v` | boolean | `false` | Enable verbose logging |
|
||||
|
||||
#### GitHub Integration
|
||||
|
||||
| Flag | Short | Type | Default | Description |
|
||||
|------|-------|------|---------|-------------|
|
||||
| `--github-token` | | string | | GitHub personal access token (or use GITHUB_TOKEN env) |
|
||||
| `--no-dependencies` | | boolean | `false` | Disable dependency analysis |
|
||||
|
||||
### Examples
|
||||
|
||||
#### Basic Generation
|
||||
|
||||
```bash
|
||||
# Generate with default settings
|
||||
gh-action-readme gen
|
||||
|
||||
# Generate from specific file
|
||||
gh-action-readme gen action.yml
|
||||
|
||||
# Generate from directory
|
||||
gh-action-readme gen ./actions/checkout/
|
||||
```
|
||||
|
||||
#### Output Formats
|
||||
|
||||
```bash
|
||||
# Markdown (default)
|
||||
gh-action-readme gen --output-format md
|
||||
|
||||
# HTML documentation
|
||||
gh-action-readme gen --output-format html
|
||||
|
||||
# JSON metadata
|
||||
gh-action-readme gen --output-format json
|
||||
|
||||
# AsciiDoc format
|
||||
gh-action-readme gen --output-format asciidoc
|
||||
```
|
||||
|
||||
#### Custom Output
|
||||
|
||||
```bash
|
||||
# Custom filename
|
||||
gh-action-readme gen --output custom-readme.md
|
||||
|
||||
# Custom directory
|
||||
gh-action-readme gen --output-dir docs/
|
||||
|
||||
# Both custom directory and filename
|
||||
gh-action-readme gen --output-dir docs/ --output action-guide.html
|
||||
```
|
||||
|
||||
#### Themes
|
||||
|
||||
```bash
|
||||
# GitHub marketplace theme
|
||||
gh-action-readme gen --theme github
|
||||
|
||||
# GitLab CI/CD theme
|
||||
gh-action-readme gen --theme gitlab
|
||||
|
||||
# Clean minimal theme
|
||||
gh-action-readme gen --theme minimal
|
||||
|
||||
# Comprehensive professional theme
|
||||
gh-action-readme gen --theme professional
|
||||
```
|
||||
|
||||
#### Advanced Options
|
||||
|
||||
```bash
|
||||
# Recursive processing
|
||||
gh-action-readme gen --recursive --theme github
|
||||
|
||||
# With GitHub token for enhanced features
|
||||
gh-action-readme gen --github-token ghp_xxxx --verbose
|
||||
|
||||
# Quiet mode for scripts
|
||||
gh-action-readme gen --theme github --quiet
|
||||
```
|
||||
|
||||
## ✅ Validation Command
|
||||
|
||||
### Basic Syntax
|
||||
|
||||
```bash
|
||||
gh-action-readme validate [file_or_directory] [flags]
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
- **`[file_or_directory]`** - Optional path to validate
|
||||
- If omitted, validates current directory
|
||||
- Supports both files and directories
|
||||
|
||||
### Flags
|
||||
|
||||
| Flag | Short | Type | Default | Description |
|
||||
|------|-------|------|---------|-------------|
|
||||
| `--verbose` | `-v` | boolean | `false` | Show detailed validation messages |
|
||||
| `--quiet` | `-q` | boolean | `false` | Only show errors, suppress warnings |
|
||||
| `--recursive` | `-r` | boolean | `false` | Validate recursively |
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Validate current directory
|
||||
gh-action-readme validate
|
||||
|
||||
# Validate specific file
|
||||
gh-action-readme validate action.yml
|
||||
|
||||
# Verbose validation with suggestions
|
||||
gh-action-readme validate --verbose
|
||||
|
||||
# Recursive validation
|
||||
gh-action-readme validate --recursive ./actions/
|
||||
```
|
||||
|
||||
### Validation Output
|
||||
|
||||
```text
|
||||
✅ action.yml is valid
|
||||
⚠️ Warning: Missing 'branding' section for marketplace visibility
|
||||
💡 Consider adding:
|
||||
branding:
|
||||
icon: 'activity'
|
||||
color: 'blue'
|
||||
|
||||
❌ Error: Missing required field 'description'
|
||||
💡 Add: description: "Brief description of what your action does"
|
||||
```
|
||||
|
||||
## ⚙️ Configuration Commands
|
||||
|
||||
### Basic Syntax
|
||||
|
||||
```bash
|
||||
gh-action-readme config [subcommand] [flags]
|
||||
```
|
||||
|
||||
### Subcommands
|
||||
|
||||
#### `init` - Initialize Configuration
|
||||
|
||||
```bash
|
||||
gh-action-readme config init [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
- `--force` - Overwrite existing configuration
|
||||
- `--global` - Create global configuration (default: user-specific)
|
||||
|
||||
#### `show` - Display Configuration
|
||||
|
||||
```bash
|
||||
gh-action-readme config show [key] [flags]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Show all configuration
|
||||
gh-action-readme config show
|
||||
|
||||
# Show specific key
|
||||
gh-action-readme config show theme
|
||||
|
||||
# Show with file paths
|
||||
gh-action-readme config show --paths
|
||||
```
|
||||
|
||||
#### `themes` - List Available Themes
|
||||
|
||||
```bash
|
||||
gh-action-readme config themes
|
||||
```
|
||||
|
||||
**Output:**
|
||||
|
||||
```text
|
||||
Available themes:
|
||||
github GitHub marketplace optimized theme
|
||||
gitlab GitLab CI/CD focused theme
|
||||
minimal Clean, minimal documentation
|
||||
professional Comprehensive enterprise theme
|
||||
default Original simple theme
|
||||
```
|
||||
|
||||
#### `wizard` - Interactive Configuration
|
||||
|
||||
```bash
|
||||
gh-action-readme config wizard [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
- `--format` - Export format: yaml (default), json, toml
|
||||
- `--output` - Output file path
|
||||
- `--no-github-token` - Skip GitHub token setup
|
||||
|
||||
**Example:**
|
||||
|
||||
```bash
|
||||
gh-action-readme config wizard --format json --output config.json
|
||||
```
|
||||
|
||||
#### `set` - Set Configuration Value
|
||||
|
||||
```bash
|
||||
gh-action-readme config set <key> <value>
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
gh-action-readme config set theme github
|
||||
gh-action-readme config set verbose true
|
||||
gh-action-readme config set output_format html
|
||||
```
|
||||
|
||||
#### `get` - Get Configuration Value
|
||||
|
||||
```bash
|
||||
gh-action-readme config get <key>
|
||||
```
|
||||
|
||||
#### `reset` - Reset Configuration
|
||||
|
||||
```bash
|
||||
gh-action-readme config reset [key]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Reset all configuration
|
||||
gh-action-readme config reset
|
||||
|
||||
# Reset specific key
|
||||
gh-action-readme config reset theme
|
||||
```
|
||||
|
||||
## ℹ️ Information Commands
|
||||
|
||||
### Version Command
|
||||
|
||||
```bash
|
||||
gh-action-readme version [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
- `--short` - Show version number only
|
||||
- `--json` - Output in JSON format
|
||||
|
||||
**Output:**
|
||||
|
||||
```text
|
||||
gh-action-readme version 1.2.0
|
||||
Built: 2025-08-07T10:30:00Z
|
||||
Commit: a1b2c3d
|
||||
Go: go1.24.4
|
||||
Platform: linux/amd64
|
||||
```
|
||||
|
||||
### Help Command
|
||||
|
||||
```bash
|
||||
gh-action-readme help [command]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# General help
|
||||
gh-action-readme help
|
||||
|
||||
# Command-specific help
|
||||
gh-action-readme help gen
|
||||
gh-action-readme help config wizard
|
||||
```
|
||||
|
||||
## 🌍 Global Flags
|
||||
|
||||
These flags are available for all commands:
|
||||
|
||||
| Flag | Short | Type | Default | Description |
|
||||
|------|-------|------|---------|-------------|
|
||||
| `--config` | | string | | Custom configuration file path |
|
||||
| `--help` | `-h` | boolean | `false` | Show help for command |
|
||||
| `--quiet` | `-q` | boolean | `false` | Suppress non-error output |
|
||||
| `--verbose` | `-v` | boolean | `false` | Enable verbose logging |
|
||||
|
||||
## 📊 Exit Codes
|
||||
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| `0` | Success |
|
||||
| `1` | General error |
|
||||
| `2` | Invalid arguments |
|
||||
| `3` | File not found |
|
||||
| `4` | Validation failed |
|
||||
| `5` | Configuration error |
|
||||
| `6` | GitHub API error |
|
||||
| `7` | Template error |
|
||||
|
||||
## 🔧 Environment Variables
|
||||
|
||||
### Configuration Override
|
||||
|
||||
- `GH_ACTION_README_THEME` - Default theme
|
||||
- `GH_ACTION_README_OUTPUT_FORMAT` - Default output format
|
||||
- `GH_ACTION_README_OUTPUT_DIR` - Default output directory
|
||||
- `GH_ACTION_README_VERBOSE` - Enable verbose mode (true/false)
|
||||
- `GH_ACTION_README_QUIET` - Enable quiet mode (true/false)
|
||||
|
||||
### GitHub Integration
|
||||
|
||||
- `GITHUB_TOKEN` - GitHub personal access token
|
||||
- `GH_ACTION_README_NO_DEPENDENCIES` - Disable dependency analysis
|
||||
|
||||
### Advanced Options
|
||||
|
||||
- `GH_ACTION_README_CONFIG` - Custom configuration file path
|
||||
- `GH_ACTION_README_CACHE_TTL` - Cache TTL in seconds
|
||||
- `GH_ACTION_README_TIMEOUT` - Request timeout in seconds
|
||||
|
||||
## 🎯 Advanced Usage Patterns
|
||||
|
||||
### Batch Processing
|
||||
|
||||
```bash
|
||||
# Process multiple actions with custom themes
|
||||
for dir in actions/*/; do
|
||||
gh-action-readme gen "$dir" --theme github --output "$dir/README.md"
|
||||
done
|
||||
|
||||
# Generate docs for all formats
|
||||
for format in md html json asciidoc; do
|
||||
gh-action-readme gen --output-format "$format" --output "docs/action.$format"
|
||||
done
|
||||
```
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
```bash
|
||||
# GitHub Actions workflow
|
||||
- name: Generate Action Documentation
|
||||
run: |
|
||||
gh-action-readme gen --theme github --output README.md
|
||||
git add README.md
|
||||
git commit -m "docs: update action documentation" || exit 0
|
||||
|
||||
# GitLab CI
|
||||
generate_docs:
|
||||
script:
|
||||
- gh-action-readme gen --theme gitlab --output-format html --output docs/
|
||||
artifacts:
|
||||
paths:
|
||||
- docs/
|
||||
```
|
||||
|
||||
### Conditional Processing
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Smart theme selection based on repository
|
||||
if [[ -f ".gitlab-ci.yml" ]]; then
|
||||
THEME="gitlab"
|
||||
elif [[ -f "package.json" ]]; then
|
||||
THEME="github"
|
||||
else
|
||||
THEME="minimal"
|
||||
fi
|
||||
|
||||
gh-action-readme gen --theme "$THEME" --verbose
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
# Generate with error handling
|
||||
if gh-action-readme gen --theme github --quiet; then
|
||||
echo "✅ Documentation generated successfully"
|
||||
else
|
||||
exit_code=$?
|
||||
echo "❌ Documentation generation failed (exit code: $exit_code)"
|
||||
|
||||
case $exit_code in
|
||||
3) echo "💡 Make sure action.yml exists in the current directory" ;;
|
||||
4) echo "💡 Run 'gh-action-readme validate' to check for issues" ;;
|
||||
6) echo "💡 Check your GitHub token and network connection" ;;
|
||||
*) echo "💡 Run with --verbose flag for more details" ;;
|
||||
esac
|
||||
|
||||
exit $exit_code
|
||||
fi
|
||||
```
|
||||
|
||||
## 🔍 Debugging & Troubleshooting
|
||||
|
||||
### Debug Output
|
||||
|
||||
```bash
|
||||
# Maximum verbosity
|
||||
gh-action-readme gen --verbose
|
||||
|
||||
# Configuration debugging
|
||||
gh-action-readme config show --debug
|
||||
|
||||
# Validation debugging
|
||||
gh-action-readme validate --verbose
|
||||
```
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Command not found:**
|
||||
|
||||
```bash
|
||||
# Check installation
|
||||
which gh-action-readme
|
||||
gh-action-readme version
|
||||
```
|
||||
|
||||
**Permission denied:**
|
||||
|
||||
```bash
|
||||
# Check file permissions
|
||||
ls -la action.yml
|
||||
chmod 644 action.yml
|
||||
```
|
||||
|
||||
**GitHub API rate limit:**
|
||||
|
||||
```bash
|
||||
# Use GitHub token
|
||||
export GITHUB_TOKEN=your_token_here
|
||||
gh-action-readme gen --verbose
|
||||
```
|
||||
|
||||
**Template errors:**
|
||||
|
||||
```bash
|
||||
# Validate action.yml first
|
||||
gh-action-readme validate --verbose
|
||||
```
|
||||
330
docs/configuration.md
Normal file
330
docs/configuration.md
Normal file
@@ -0,0 +1,330 @@
|
||||
# Configuration
|
||||
|
||||
Configure gh-action-readme with persistent settings, environment variables, and advanced options.
|
||||
|
||||
## 📁 Configuration File
|
||||
|
||||
Create persistent settings with XDG-compliant configuration:
|
||||
|
||||
```bash
|
||||
gh-action-readme config init
|
||||
```
|
||||
|
||||
### Default Location
|
||||
|
||||
- **Linux/macOS**: `~/.config/gh-action-readme/config.yaml`
|
||||
- **Windows**: `%APPDATA%\gh-action-readme\config.yaml`
|
||||
|
||||
### Configuration Format
|
||||
|
||||
```yaml
|
||||
# ~/.config/gh-action-readme/config.yaml
|
||||
theme: github
|
||||
output_format: md
|
||||
output_dir: .
|
||||
verbose: false
|
||||
github_token: ""
|
||||
dependencies_enabled: true
|
||||
cache_ttl: 3600
|
||||
```
|
||||
|
||||
## 🔧 Configuration Options
|
||||
|
||||
### Core Settings
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `theme` | string | `default` | Default theme to use |
|
||||
| `output_format` | string | `md` | Default output format |
|
||||
| `output_dir` | string | `.` | Default output directory |
|
||||
| `verbose` | boolean | `false` | Enable verbose logging |
|
||||
|
||||
### GitHub Integration
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `github_token` | string | `""` | GitHub personal access token |
|
||||
| `dependencies_enabled` | boolean | `true` | Enable dependency analysis |
|
||||
| `rate_limit_delay` | int | `1000` | Delay between API calls (ms) |
|
||||
|
||||
### Performance Settings
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `cache_ttl` | int | `3600` | Cache TTL in seconds |
|
||||
| `concurrent_requests` | int | `3` | Max concurrent GitHub API requests |
|
||||
| `timeout` | int | `30` | Request timeout in seconds |
|
||||
|
||||
## 🌍 Environment Variables
|
||||
|
||||
Override configuration with environment variables:
|
||||
|
||||
```bash
|
||||
# Core settings
|
||||
export GH_ACTION_README_THEME=github
|
||||
export GH_ACTION_README_OUTPUT_FORMAT=html
|
||||
export GH_ACTION_README_OUTPUT_DIR=docs
|
||||
export GH_ACTION_README_VERBOSE=true
|
||||
|
||||
# GitHub settings
|
||||
export GITHUB_TOKEN=your_token_here
|
||||
export GH_ACTION_README_DEPENDENCIES=true
|
||||
|
||||
# Performance settings
|
||||
export GH_ACTION_README_CACHE_TTL=7200
|
||||
export GH_ACTION_README_TIMEOUT=60
|
||||
```
|
||||
|
||||
### Environment Variable Priority
|
||||
|
||||
1. Command line flags (highest priority)
|
||||
2. Environment variables
|
||||
3. Configuration file
|
||||
4. Built-in defaults (lowest priority)
|
||||
|
||||
## 🎛️ Interactive Configuration
|
||||
|
||||
Use the interactive wizard for guided setup:
|
||||
|
||||
```bash
|
||||
gh-action-readme config wizard
|
||||
```
|
||||
|
||||
### Wizard Features
|
||||
|
||||
- **Auto-detection** of project settings
|
||||
- **GitHub token** setup with validation
|
||||
- **Theme preview** with examples
|
||||
- **Export options** (YAML, JSON, TOML)
|
||||
- **Real-time validation** with suggestions
|
||||
|
||||
### Wizard Example
|
||||
|
||||
```bash
|
||||
$ gh-action-readme config wizard
|
||||
|
||||
✨ Welcome to gh-action-readme configuration wizard!
|
||||
|
||||
🔍 Detected project settings:
|
||||
Repository: ivuorinen/my-action
|
||||
Language: JavaScript/TypeScript
|
||||
|
||||
📋 Select your preferences:
|
||||
Theme: github, gitlab, minimal, professional, default
|
||||
>> github
|
||||
|
||||
Output format: md, html, json, asciidoc
|
||||
>> md
|
||||
|
||||
🔑 GitHub Token (optional, for enhanced features):
|
||||
>> ghp_xxxxxxxxxxxx
|
||||
✅ Token validated successfully!
|
||||
|
||||
💾 Export configuration as:
|
||||
Format: yaml, json, toml
|
||||
>> yaml
|
||||
|
||||
✅ Configuration saved to ~/.config/gh-action-readme/config.yaml
|
||||
```
|
||||
|
||||
## 🎨 Theme Configuration
|
||||
|
||||
### Built-in Themes
|
||||
|
||||
```bash
|
||||
# List available themes
|
||||
gh-action-readme config themes
|
||||
|
||||
# Set default theme
|
||||
gh-action-readme config set theme github
|
||||
```
|
||||
|
||||
### Custom Themes
|
||||
|
||||
Create custom themes by copying existing ones:
|
||||
|
||||
```bash
|
||||
# Copy existing theme
|
||||
cp -r templates/themes/github templates/themes/custom
|
||||
|
||||
# Edit template
|
||||
vim templates/themes/custom/readme.tmpl
|
||||
|
||||
# Use custom theme
|
||||
gh-action-readme gen --theme custom
|
||||
```
|
||||
|
||||
### Theme Directory Structure
|
||||
|
||||
```text
|
||||
templates/themes/your-theme/
|
||||
├── readme.tmpl # Main template
|
||||
├── partials/ # Optional partial templates
|
||||
│ ├── header.tmpl
|
||||
│ ├── inputs.tmpl
|
||||
│ └── examples.tmpl
|
||||
└── assets/ # Optional theme assets
|
||||
├── styles.css
|
||||
└── logo.png
|
||||
```
|
||||
|
||||
## 🔐 GitHub Token Configuration
|
||||
|
||||
### Creating a Token
|
||||
|
||||
1. Go to GitHub Settings → Developer settings → Personal access tokens
|
||||
2. Generate new token with `public_repo` scope
|
||||
3. Copy token and save securely
|
||||
|
||||
### Setting Token
|
||||
|
||||
```bash
|
||||
# Environment variable (recommended)
|
||||
export GITHUB_TOKEN=your_token_here
|
||||
|
||||
# Configuration file
|
||||
gh-action-readme config set github_token your_token_here
|
||||
|
||||
# Command line (least secure)
|
||||
gh-action-readme gen --github-token your_token_here
|
||||
```
|
||||
|
||||
### Token Benefits
|
||||
|
||||
- **Higher rate limits** (5000 requests/hour vs 60)
|
||||
- **Dependency analysis** with detailed metadata
|
||||
- **Private repository** access
|
||||
- **Enhanced error messages** for API issues
|
||||
|
||||
## 📊 Cache Configuration
|
||||
|
||||
### Cache Settings
|
||||
|
||||
```yaml
|
||||
# Cache configuration
|
||||
cache_enabled: true
|
||||
cache_dir: ~/.cache/gh-action-readme
|
||||
cache_ttl: 3600 # 1 hour in seconds
|
||||
cache_max_size: 100 # MB
|
||||
```
|
||||
|
||||
### Cache Management
|
||||
|
||||
```bash
|
||||
# Clear cache
|
||||
gh-action-readme config clear-cache
|
||||
|
||||
# Check cache status
|
||||
gh-action-readme config cache-status
|
||||
|
||||
# Set cache TTL
|
||||
gh-action-readme config set cache_ttl 7200 # 2 hours
|
||||
```
|
||||
|
||||
## 🔧 Advanced Configuration
|
||||
|
||||
### Custom Output Templates
|
||||
|
||||
```yaml
|
||||
# Custom output naming patterns
|
||||
output_patterns:
|
||||
md: "${name}-README.md"
|
||||
html: "docs/${name}.html"
|
||||
json: "api/${name}-metadata.json"
|
||||
```
|
||||
|
||||
### Validation Rules
|
||||
|
||||
```yaml
|
||||
# Custom validation settings
|
||||
validation:
|
||||
require_description: true
|
||||
require_examples: false
|
||||
max_input_count: 50
|
||||
enforce_semver: true
|
||||
```
|
||||
|
||||
### Template Variables
|
||||
|
||||
```yaml
|
||||
# Custom template variables
|
||||
template_vars:
|
||||
organization: "my-org"
|
||||
support_email: "support@example.com"
|
||||
docs_url: "https://docs.example.com"
|
||||
```
|
||||
|
||||
## 📝 Configuration Commands
|
||||
|
||||
### View Configuration
|
||||
|
||||
```bash
|
||||
# Show current config
|
||||
gh-action-readme config show
|
||||
|
||||
# Show specific setting
|
||||
gh-action-readme config get theme
|
||||
```
|
||||
|
||||
### Update Configuration
|
||||
|
||||
```bash
|
||||
# Set individual values
|
||||
gh-action-readme config set theme professional
|
||||
gh-action-readme config set verbose true
|
||||
|
||||
# Reset to defaults
|
||||
gh-action-readme config reset
|
||||
|
||||
# Remove config file
|
||||
gh-action-readme config delete
|
||||
```
|
||||
|
||||
### Export/Import Configuration
|
||||
|
||||
```bash
|
||||
# Export current config
|
||||
gh-action-readme config export --format json > config.json
|
||||
|
||||
# Import configuration
|
||||
gh-action-readme config import config.json
|
||||
|
||||
# Merge configurations
|
||||
gh-action-readme config merge other-config.yaml
|
||||
```
|
||||
|
||||
## 🔍 Debugging Configuration
|
||||
|
||||
### Verbose Mode
|
||||
|
||||
```bash
|
||||
# Enable verbose output
|
||||
gh-action-readme gen --verbose
|
||||
|
||||
# Set in config
|
||||
gh-action-readme config set verbose true
|
||||
```
|
||||
|
||||
### Configuration Validation
|
||||
|
||||
```bash
|
||||
# Validate current configuration
|
||||
gh-action-readme config validate
|
||||
|
||||
# Test configuration with dry run
|
||||
gh-action-readme gen --dry-run --verbose
|
||||
```
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
```bash
|
||||
# Show effective configuration (merged from all sources)
|
||||
gh-action-readme config effective
|
||||
|
||||
# Show configuration file locations
|
||||
gh-action-readme config paths
|
||||
|
||||
# Reset corrupted configuration
|
||||
rm ~/.config/gh-action-readme/config.yaml
|
||||
gh-action-readme config init
|
||||
```
|
||||
447
docs/development.md
Normal file
447
docs/development.md
Normal file
@@ -0,0 +1,447 @@
|
||||
# Development Guide
|
||||
|
||||
Comprehensive guide for developing and contributing to gh-action-readme.
|
||||
|
||||
## 🚨 CRITICAL: README Protection
|
||||
|
||||
**NEVER overwrite `/README.md`** - The root README.md is the main project documentation.
|
||||
|
||||
**For testing generation commands:**
|
||||
|
||||
```bash
|
||||
# New enhanced targeting (recommended)
|
||||
gh-action-readme gen testdata/example-action/
|
||||
gh-action-readme gen testdata/composite-action/action.yml
|
||||
|
||||
# Traditional method (still supported)
|
||||
cd testdata/
|
||||
../gh-action-readme gen [options]
|
||||
```
|
||||
|
||||
## 🛠️ Development Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **Go 1.24+** (required)
|
||||
- **golangci-lint** (for linting)
|
||||
- **pre-commit** (for git hooks)
|
||||
- **Docker** (optional, for containerized testing)
|
||||
|
||||
### Quick Start
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://github.com/ivuorinen/gh-action-readme.git
|
||||
cd gh-action-readme
|
||||
|
||||
# Install development tools
|
||||
make devtools
|
||||
|
||||
# Install pre-commit hooks
|
||||
make pre-commit-install
|
||||
|
||||
# Build and test
|
||||
make build
|
||||
make test
|
||||
make lint
|
||||
```
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
### Core Components
|
||||
|
||||
- **`main.go`** - CLI with Cobra framework, enhanced gen command
|
||||
- **`internal/generator.go`** - Core generation logic with custom output paths
|
||||
- **`internal/config.go`** - Viper configuration (XDG compliant)
|
||||
- **`internal/output.go`** - Colored terminal output with progress bars
|
||||
- **`internal/errors/`** - Contextual error handling with suggestions
|
||||
- **`internal/wizard/`** - Interactive configuration wizard
|
||||
- **`internal/progress.go`** - Progress indicators for batch operations
|
||||
|
||||
### Template System
|
||||
|
||||
- **`templates/readme.tmpl`** - Default template
|
||||
- **`templates/themes/`** - Theme-specific templates
|
||||
- `github/` - GitHub-style with badges
|
||||
- `gitlab/` - GitLab CI/CD focused
|
||||
- `minimal/` - Clean, concise
|
||||
- `professional/` - Comprehensive with ToC
|
||||
- `asciidoc/` - AsciiDoc format
|
||||
|
||||
### Testing Framework
|
||||
|
||||
- **`testutil/`** - Comprehensive testing utilities
|
||||
- **`testdata/`** - Test fixtures and sample actions
|
||||
- **Table-driven tests** - Consistent testing patterns
|
||||
- **Mock implementations** - Isolated unit tests
|
||||
|
||||
## 🧪 Testing Strategy
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# All tests
|
||||
make test
|
||||
|
||||
# With coverage
|
||||
make test-coverage
|
||||
|
||||
# Specific package
|
||||
go test ./internal/generator
|
||||
|
||||
# Verbose output
|
||||
go test -v ./...
|
||||
|
||||
# Race condition detection
|
||||
go test -race ./...
|
||||
```
|
||||
|
||||
### Test Types
|
||||
|
||||
**Unit Tests** (`*_test.go`):
|
||||
|
||||
```bash
|
||||
go test ./internal # Core logic tests
|
||||
go test ./testutil # Test framework tests
|
||||
```
|
||||
|
||||
**Integration Tests** (`*_integration_test.go`):
|
||||
|
||||
```bash
|
||||
go test -tags=integration ./...
|
||||
```
|
||||
|
||||
**Comprehensive Tests** (`comprehensive_test.go`):
|
||||
|
||||
```bash
|
||||
go test ./internal -run Comprehensive
|
||||
```
|
||||
|
||||
### Testing Best Practices
|
||||
|
||||
1. **Use testutil framework** for consistent test patterns
|
||||
2. **Table-driven tests** for multiple scenarios
|
||||
3. **Mock external dependencies** (GitHub API, filesystem)
|
||||
4. **Test error conditions** and edge cases
|
||||
5. **Verify thread safety** with race detection
|
||||
|
||||
### Test Coverage
|
||||
|
||||
Current coverage: **51.2%** overall
|
||||
|
||||
- **Cache module**: 91.4%
|
||||
- **Errors module**: 91.5%
|
||||
- **Git detector**: 78.4%
|
||||
- **Validation**: 76.2%
|
||||
|
||||
Target: **>80%** coverage for all new code
|
||||
|
||||
## 🔧 Build System
|
||||
|
||||
### Makefile Targets
|
||||
|
||||
```bash
|
||||
# Building
|
||||
make build # Build binary
|
||||
make clean # Clean build artifacts
|
||||
|
||||
# Testing
|
||||
make test # Run all tests
|
||||
make test-coverage # Run tests with coverage
|
||||
make lint # Run all linters
|
||||
|
||||
# Development
|
||||
make devtools # Install dev tools
|
||||
make format # Format code
|
||||
make pre-commit-install # Install git hooks
|
||||
|
||||
# Security
|
||||
make security # Run security scans
|
||||
make vulncheck # Go vulnerability check
|
||||
|
||||
# Dependencies
|
||||
make deps-check # Check outdated dependencies
|
||||
make deps-update # Interactive dependency updates
|
||||
```
|
||||
|
||||
### Build Configuration
|
||||
|
||||
```bash
|
||||
# Build with version info
|
||||
go build -ldflags "-X main.version=v1.0.0 -X main.commit=$(git rev-parse HEAD)"
|
||||
|
||||
# Cross-platform builds (handled by GoReleaser)
|
||||
GOOS=linux GOARCH=amd64 go build
|
||||
GOOS=darwin GOARCH=arm64 go build
|
||||
GOOS=windows GOARCH=amd64 go build
|
||||
```
|
||||
|
||||
## 📝 Code Style & Quality
|
||||
|
||||
### Linting Configuration
|
||||
|
||||
- **golangci-lint** with 35+ enabled linters
|
||||
- **EditorConfig** compliance required
|
||||
- **Pre-commit hooks** for automated checking
|
||||
- **Zero linting violations** policy
|
||||
|
||||
### Code Quality Standards
|
||||
|
||||
- ✅ **Cyclomatic complexity** <10 for all functions
|
||||
- ✅ **Test coverage** >80% for critical modules
|
||||
- ✅ **Error handling** for all possible errors
|
||||
- ✅ **Documentation** for all exported functions
|
||||
- ✅ **Thread safety** for concurrent operations
|
||||
|
||||
### Formatting Rules
|
||||
|
||||
```bash
|
||||
# Auto-format code
|
||||
make format
|
||||
|
||||
# Check formatting
|
||||
gofmt -d .
|
||||
goimports -d .
|
||||
```
|
||||
|
||||
## 🔄 Adding New Features
|
||||
|
||||
### New Theme
|
||||
|
||||
1. Create `templates/themes/THEME_NAME/readme.tmpl`
|
||||
2. Add to `resolveThemeTemplate()` in `config.go`
|
||||
3. Update `configThemesHandler()` in `main.go`
|
||||
4. Add tests and documentation
|
||||
|
||||
### New Output Format
|
||||
|
||||
1. Add constant to `generator.go`
|
||||
2. Add case to `GenerateFromFile()` switch
|
||||
3. Implement `generate[FORMAT]()` method
|
||||
4. Update CLI help and documentation
|
||||
|
||||
### New CLI Command
|
||||
|
||||
1. Add command in `main.go` using Cobra
|
||||
2. Implement handler function
|
||||
3. Add flags and validation
|
||||
4. Write tests and update documentation
|
||||
|
||||
### New Template Functions
|
||||
|
||||
Add to `templateFuncs()` in `internal/template.go`:
|
||||
|
||||
```go
|
||||
"myFunction": func(input string) string {
|
||||
// Implementation
|
||||
return processed
|
||||
},
|
||||
```
|
||||
|
||||
## 🚀 Performance Optimization
|
||||
|
||||
### Profiling
|
||||
|
||||
```bash
|
||||
# CPU profiling
|
||||
go test -cpuprofile=cpu.prof -bench=.
|
||||
go tool pprof cpu.prof
|
||||
|
||||
# Memory profiling
|
||||
go test -memprofile=mem.prof -bench=.
|
||||
go tool pprof mem.prof
|
||||
|
||||
# Benchmark testing
|
||||
go test -bench=. -benchmem
|
||||
```
|
||||
|
||||
### Performance Guidelines
|
||||
|
||||
- **Use sync.Pool** for frequently allocated objects
|
||||
- **Implement caching** for expensive operations
|
||||
- **Minimize memory allocations** in hot paths
|
||||
- **Concurrent processing** for I/O bound operations
|
||||
- **Profile before optimizing**
|
||||
|
||||
## 🔐 Security Practices
|
||||
|
||||
### Security Scanning
|
||||
|
||||
```bash
|
||||
make security # Run all scans
|
||||
make vulncheck # Go vulnerabilities
|
||||
make trivy # Filesystem scan
|
||||
make gitleaks # Secrets detection
|
||||
```
|
||||
|
||||
### Secure Coding
|
||||
|
||||
- **Validate all inputs** especially user-provided data
|
||||
- **Use secure defaults** for all configurations
|
||||
- **Sanitize file paths** to prevent directory traversal
|
||||
- **Handle secrets safely** never log or expose tokens
|
||||
- **Regular dependency updates** with security patches
|
||||
|
||||
### GitHub Token Handling
|
||||
|
||||
```go
|
||||
// ❌ Wrong - logging token
|
||||
log.Printf("Using token: %s", token)
|
||||
|
||||
// ✅ Correct - masking sensitive data
|
||||
log.Printf("Using token: %s", maskToken(token))
|
||||
|
||||
func maskToken(token string) string {
|
||||
if len(token) < 8 {
|
||||
return "***"
|
||||
}
|
||||
return token[:4] + "***" + token[len(token)-4:]
|
||||
}
|
||||
```
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
### Documentation Standards
|
||||
|
||||
- **godoc comments** for all exported functions
|
||||
- **README updates** for user-facing changes
|
||||
- **CHANGELOG entries** following Keep a Changelog format
|
||||
- **Architecture Decision Records** for significant changes
|
||||
|
||||
### Writing Guidelines
|
||||
|
||||
```go
|
||||
// Package generator provides core documentation generation functionality.
|
||||
//
|
||||
// The generator processes GitHub Action YAML files and produces formatted
|
||||
// documentation in multiple output formats (Markdown, HTML, JSON, AsciiDoc).
|
||||
package generator
|
||||
|
||||
// GenerateReadme creates formatted documentation from an ActionYML struct.
|
||||
//
|
||||
// The function applies the specified theme and output format to generate
|
||||
// comprehensive documentation including input/output tables, usage examples,
|
||||
// and metadata sections.
|
||||
//
|
||||
// Parameters:
|
||||
// - action: Parsed action.yml data structure
|
||||
// - theme: Template theme name (github, gitlab, minimal, professional, default)
|
||||
// - format: Output format (md, html, json, asciidoc)
|
||||
//
|
||||
// Returns formatted documentation string and any processing error.
|
||||
func GenerateReadme(action *ActionYML, theme, format string) (string, error) {
|
||||
// Implementation...
|
||||
}
|
||||
```
|
||||
|
||||
## 🤝 Contributing Guidelines
|
||||
|
||||
### Contribution Process
|
||||
|
||||
1. **Fork repository** and create feature branch
|
||||
2. **Make changes** following code style guidelines
|
||||
3. **Add tests** for new functionality
|
||||
4. **Update documentation** as needed
|
||||
5. **Run quality checks** (`make test lint`)
|
||||
6. **Submit pull request** with clear description
|
||||
|
||||
### Pull Request Guidelines
|
||||
|
||||
- **Clear title** describing the change
|
||||
- **Detailed description** of what and why
|
||||
- **Link related issues** if applicable
|
||||
- **Include tests** for new features
|
||||
- **Update documentation** for user-facing changes
|
||||
- **Ensure CI passes** all quality checks
|
||||
|
||||
### Code Review Process
|
||||
|
||||
- **Two approvals** required for merging
|
||||
- **All checks must pass** (tests, linting, security)
|
||||
- **Documentation review** for user-facing changes
|
||||
- **Performance impact** assessment for core changes
|
||||
|
||||
## 🐛 Debugging
|
||||
|
||||
### Debug Mode
|
||||
|
||||
```bash
|
||||
# Enable verbose output
|
||||
gh-action-readme gen --verbose
|
||||
|
||||
# Debug configuration
|
||||
gh-action-readme config show --debug
|
||||
|
||||
# Trace execution
|
||||
TRACE=1 gh-action-readme gen
|
||||
```
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Template Errors:**
|
||||
|
||||
```bash
|
||||
# Validate action.yml syntax
|
||||
gh-action-readme validate --verbose
|
||||
|
||||
# Check template syntax
|
||||
gh-action-readme gen --dry-run --verbose
|
||||
```
|
||||
|
||||
**GitHub API Issues:**
|
||||
|
||||
```bash
|
||||
# Check rate limits
|
||||
curl -H "Authorization: token $GITHUB_TOKEN" \
|
||||
https://api.github.com/rate_limit
|
||||
|
||||
# Test API access
|
||||
gh-action-readme gen --verbose --github-token $GITHUB_TOKEN
|
||||
```
|
||||
|
||||
**Build Issues:**
|
||||
|
||||
```bash
|
||||
# Clean and rebuild
|
||||
make clean
|
||||
make build
|
||||
|
||||
# Check dependencies
|
||||
go mod verify
|
||||
go mod tidy
|
||||
```
|
||||
|
||||
## 📊 Metrics & Monitoring
|
||||
|
||||
### Performance Metrics
|
||||
|
||||
- **Generation time** per action
|
||||
- **GitHub API** request count and timing
|
||||
- **Memory usage** during processing
|
||||
- **Cache hit rates** for repeated operations
|
||||
|
||||
### Quality Metrics
|
||||
|
||||
- **Test coverage** percentage
|
||||
- **Linting violations** count
|
||||
- **Security vulnerabilities** detected
|
||||
- **Documentation coverage** for public APIs
|
||||
|
||||
### Tracking Tools
|
||||
|
||||
```bash
|
||||
# Performance benchmarks
|
||||
go test -bench=. -benchmem ./...
|
||||
|
||||
# Memory profiling
|
||||
go test -memprofile=mem.prof ./...
|
||||
|
||||
# Coverage reporting
|
||||
go test -coverprofile=coverage.out ./...
|
||||
go tool cover -html=coverage.out
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Status**: ENTERPRISE READY ✅
|
||||
*Enhanced gen command, thread-safety, comprehensive testing, and enterprise features fully implemented.*
|
||||
149
docs/installation.md
Normal file
149
docs/installation.md
Normal file
@@ -0,0 +1,149 @@
|
||||
# Installation
|
||||
|
||||
Multiple installation options are available for gh-action-readme.
|
||||
|
||||
## 📦 Binary Releases (Recommended)
|
||||
|
||||
Download pre-built binaries for your platform from the [latest release](https://github.com/ivuorinen/gh-action-readme/releases/latest).
|
||||
|
||||
### Linux x86_64
|
||||
|
||||
```bash
|
||||
curl -L https://github.com/ivuorinen/gh-action-readme/releases/latest/download/gh-action-readme_Linux_x86_64.tar.gz | tar -xz
|
||||
sudo mv gh-action-readme /usr/local/bin/
|
||||
```
|
||||
|
||||
### macOS x86_64 (Intel)
|
||||
|
||||
```bash
|
||||
curl -L https://github.com/ivuorinen/gh-action-readme/releases/latest/download/gh-action-readme_Darwin_x86_64.tar.gz | tar -xz
|
||||
sudo mv gh-action-readme /usr/local/bin/
|
||||
```
|
||||
|
||||
### macOS ARM64 (Apple Silicon)
|
||||
|
||||
```bash
|
||||
curl -L https://github.com/ivuorinen/gh-action-readme/releases/latest/download/gh-action-readme_Darwin_arm64.tar.gz | tar -xz
|
||||
sudo mv gh-action-readme /usr/local/bin/
|
||||
```
|
||||
|
||||
### Windows x86_64
|
||||
|
||||
```powershell
|
||||
# PowerShell
|
||||
Invoke-WebRequest -Uri "https://github.com/ivuorinen/gh-action-readme/releases/latest/download/gh-action-readme_Windows_x86_64.zip" -OutFile "gh-action-readme.zip"
|
||||
Expand-Archive gh-action-readme.zip
|
||||
```
|
||||
|
||||
## 🍺 Package Managers
|
||||
|
||||
### Homebrew (macOS/Linux)
|
||||
|
||||
```bash
|
||||
brew install ivuorinen/tap/gh-action-readme
|
||||
```
|
||||
|
||||
### Scoop (Windows)
|
||||
|
||||
```powershell
|
||||
scoop bucket add ivuorinen https://github.com/ivuorinen/scoop-bucket.git
|
||||
scoop install gh-action-readme
|
||||
```
|
||||
|
||||
### Go Install
|
||||
|
||||
```bash
|
||||
go install github.com/ivuorinen/gh-action-readme@latest
|
||||
```
|
||||
|
||||
## 🐳 Docker
|
||||
|
||||
Run directly from Docker without installation:
|
||||
|
||||
```bash
|
||||
# Latest release
|
||||
docker run --rm -v $(pwd):/workspace ghcr.io/ivuorinen/gh-action-readme:latest gen
|
||||
|
||||
# Specific version
|
||||
docker run --rm -v $(pwd):/workspace ghcr.io/ivuorinen/gh-action-readme:v1.0.0 gen
|
||||
```
|
||||
|
||||
### Docker Compose
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
services:
|
||||
gh-action-readme:
|
||||
image: ghcr.io/ivuorinen/gh-action-readme:latest
|
||||
volumes:
|
||||
- .:/workspace
|
||||
working_dir: /workspace
|
||||
```
|
||||
|
||||
## 🔧 From Source
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Go 1.24+
|
||||
- Git
|
||||
|
||||
### Build
|
||||
|
||||
```bash
|
||||
git clone https://github.com/ivuorinen/gh-action-readme.git
|
||||
cd gh-action-readme
|
||||
make build
|
||||
```
|
||||
|
||||
### Install System-wide
|
||||
|
||||
```bash
|
||||
sudo cp gh-action-readme /usr/local/bin/
|
||||
```
|
||||
|
||||
## ✅ Verify Installation
|
||||
|
||||
```bash
|
||||
gh-action-readme version
|
||||
gh-action-readme --help
|
||||
```
|
||||
|
||||
## 🔄 Updates
|
||||
|
||||
### Binary/Package Manager
|
||||
|
||||
- **Homebrew**: `brew upgrade gh-action-readme`
|
||||
- **Scoop**: `scoop update gh-action-readme`
|
||||
- **Manual**: Download new binary and replace existing
|
||||
|
||||
### Docker
|
||||
|
||||
```bash
|
||||
docker pull ghcr.io/ivuorinen/gh-action-readme:latest
|
||||
```
|
||||
|
||||
### Go Install
|
||||
|
||||
```bash
|
||||
go install github.com/ivuorinen/gh-action-readme@latest
|
||||
```
|
||||
|
||||
## 🚫 Uninstall
|
||||
|
||||
### Binary Installation
|
||||
|
||||
```bash
|
||||
sudo rm /usr/local/bin/gh-action-readme
|
||||
```
|
||||
|
||||
### Package Managers
|
||||
|
||||
- **Homebrew**: `brew uninstall gh-action-readme`
|
||||
- **Scoop**: `scoop uninstall gh-action-readme`
|
||||
|
||||
### Configuration Files
|
||||
|
||||
```bash
|
||||
# Remove user configuration (optional)
|
||||
rm -rf ~/.config/gh-action-readme/
|
||||
```
|
||||
156
docs/roadmap.md
Normal file
156
docs/roadmap.md
Normal file
@@ -0,0 +1,156 @@
|
||||
# Roadmap
|
||||
|
||||
Strategic roadmap for gh-action-readme development and future enhancements.
|
||||
|
||||
## 🎯 Project Status
|
||||
|
||||
- **Current Quality**: A+ Excellent
|
||||
- **Target**: Industry-Leading Reference
|
||||
- **Last Major Update**: August 6, 2025 (Gen Command Enhancement & Final Polish)
|
||||
|
||||
## ✅ Recently Completed (August 2025)
|
||||
|
||||
### Enhanced Gen Command & Thread Safety
|
||||
|
||||
- **Directory/File Targeting**: Support for `gen testdata/example-action/` syntax
|
||||
- **Custom Output Filenames**: `--output custom-name.html` flag
|
||||
- **Thread Safety**: RWMutex implementation for race condition protection
|
||||
- **CI/CD Integration**: Enhanced GitHub Actions workflow
|
||||
|
||||
### Code Quality & Security
|
||||
|
||||
- **Zero Linting Violations**: Complete golangci-lint compliance
|
||||
- **EditorConfig Compliance**: Consistent formatting across codebase
|
||||
- **Security Hardening**: Integrated govulncheck, Trivy, gitleaks, CodeQL
|
||||
- **Dependency Updates**: Latest Go 1.24, security patches applied
|
||||
|
||||
### Developer Experience
|
||||
|
||||
- **Contextual Error Handling**: 14 error codes with actionable suggestions
|
||||
- **Interactive Wizard**: Step-by-step project configuration
|
||||
- **Progress Indicators**: Visual feedback for long operations
|
||||
- **Enhanced Documentation**: Comprehensive guides and examples
|
||||
|
||||
## 🚀 High Priority (Next 6 months)
|
||||
|
||||
### Performance Optimization
|
||||
|
||||
- **Concurrent GitHub API Processing**: 5-10x faster dependency analysis
|
||||
- **GraphQL Migration**: Reduce API calls by 70-80%
|
||||
- **Memory Optimization**: Implement pooling for large-scale operations
|
||||
- **Benchmark Testing**: Performance regression detection
|
||||
|
||||
### Advanced Features
|
||||
|
||||
- **Plugin System**: Extensible architecture for custom functionality
|
||||
- **Multi-Repository Batch Processing**: Enterprise-scale operations
|
||||
- **Vulnerability Scanning**: Security analysis integration
|
||||
- **Advanced Analytics**: Usage patterns and optimization insights
|
||||
|
||||
## 💡 Medium Priority (6-12 months)
|
||||
|
||||
### Quality Assurance
|
||||
|
||||
- **Property-Based Testing**: Edge case discovery with automated test generation
|
||||
- **Mutation Testing**: Test suite quality validation
|
||||
- **Interface Abstractions**: Better testability and dependency injection
|
||||
- **Event-Driven Architecture**: Improved observability and extensibility
|
||||
|
||||
### Developer Tools
|
||||
|
||||
- **API Documentation**: Comprehensive godoc coverage
|
||||
- **Configuration Validation**: JSON schema-based validation
|
||||
- **VS Code Extension**: IDE integration
|
||||
- **IntelliJ Plugin**: JetBrains IDE support
|
||||
|
||||
## 🌟 Strategic Initiatives (12+ months)
|
||||
|
||||
### Enterprise Features
|
||||
|
||||
- **Web Dashboard**: Team collaboration and centralized management
|
||||
- **API Server Mode**: RESTful API for CI/CD integration
|
||||
- **Cloud Service Integration**: AWS, Azure, Google Cloud support
|
||||
- **Docker Hub Integration**: Automated documentation for containers
|
||||
|
||||
### Innovation
|
||||
|
||||
- **AI-Powered Suggestions**: ML-based template and configuration recommendations
|
||||
- **Integration Ecosystem**: GitHub Apps, GitLab CI/CD, Jenkins plugins
|
||||
- **Advanced Template Engine**: More powerful customization capabilities
|
||||
- **Registry Integration**: npm, PyPI, Docker Hub documentation automation
|
||||
|
||||
## 📊 Success Metrics
|
||||
|
||||
### Performance Targets
|
||||
|
||||
- **50% improvement** in processing speed
|
||||
- **Zero high-severity** vulnerabilities
|
||||
- **90% reduction** in configuration errors
|
||||
- **>95% test coverage** for all new features
|
||||
|
||||
### Adoption Goals
|
||||
|
||||
- **10x increase** in GitHub stars and downloads
|
||||
- **Active plugin ecosystem** with 5+ community plugins
|
||||
- **Enterprise adoption** by major organizations
|
||||
- **Community contributions** from 50+ contributors
|
||||
|
||||
## 🛠️ Implementation Guidelines
|
||||
|
||||
### Development Process
|
||||
|
||||
1. **Design documents** for medium+ complexity features
|
||||
2. **Test-driven development** with comprehensive coverage
|
||||
3. **Semantic versioning** for all releases
|
||||
4. **Backward compatibility** with migration paths
|
||||
5. **Security-first** development practices
|
||||
|
||||
### Quality Gates
|
||||
|
||||
- **Code Coverage**: >80% for all new code
|
||||
- **Security Scanning**: Pass all SAST and dependency scans
|
||||
- **Performance**: No regression in benchmark tests
|
||||
- **Documentation**: Complete coverage for public APIs
|
||||
|
||||
## 🤝 Community Involvement
|
||||
|
||||
### Contribution Areas
|
||||
|
||||
- **Theme Development**: New visual themes and templates
|
||||
- **Plugin Creation**: Extending core functionality
|
||||
- **Integration Development**: CI/CD and tool integrations
|
||||
- **Documentation**: Guides, tutorials, and examples
|
||||
- **Testing**: Edge cases and platform coverage
|
||||
|
||||
### Maintainer Support
|
||||
|
||||
- **Code Reviews**: Expert feedback on contributions
|
||||
- **Mentorship**: Guidance for new contributors
|
||||
- **Feature Requests**: Community-driven roadmap input
|
||||
- **Bug Reports**: Rapid response and resolution
|
||||
|
||||
## 📈 Long-term Vision
|
||||
|
||||
Transform gh-action-readme into the **definitive tooling solution** for GitHub Actions documentation, with:
|
||||
|
||||
- **Universal Adoption**: Standard tool for action developers
|
||||
- **Enterprise Integration**: Built into major CI/CD platforms
|
||||
- **AI Enhancement**: Intelligent documentation generation
|
||||
- **Community Ecosystem**: Thriving plugin and theme marketplace
|
||||
- **Industry Leadership**: Setting standards for action tooling
|
||||
|
||||
## 🔄 Roadmap Updates
|
||||
|
||||
This roadmap is reviewed and updated quarterly based on:
|
||||
|
||||
- Community feedback and feature requests
|
||||
- Technology evolution and new capabilities
|
||||
- Performance metrics and user analytics
|
||||
- Strategic partnerships and integrations
|
||||
- Security landscape and compliance requirements
|
||||
|
||||
---
|
||||
|
||||
**Next Review**: November 2025
|
||||
**Current Focus**: Performance optimization and enterprise features
|
||||
**Community Input**: [GitHub Discussions](https://github.com/ivuorinen/gh-action-readme/discussions)
|
||||
172
docs/security.md
Normal file
172
docs/security.md
Normal file
@@ -0,0 +1,172 @@
|
||||
# Security Policy
|
||||
|
||||
## Supported Versions
|
||||
|
||||
We provide security updates for the following versions of gh-action-readme:
|
||||
|
||||
| Version | Supported |
|
||||
| ------- | ------------------ |
|
||||
| latest | :white_check_mark: |
|
||||
| < latest| :x: |
|
||||
|
||||
## Reporting a Vulnerability
|
||||
|
||||
We take security vulnerabilities seriously. If you discover a security issue in gh-action-readme, please report it responsibly.
|
||||
|
||||
### How to Report
|
||||
|
||||
1. **Do NOT create a public GitHub issue** for security vulnerabilities
|
||||
2. Send an email to [security@ivuorinen.dev](mailto:security@ivuorinen.dev) with:
|
||||
|
||||
- Description of the vulnerability
|
||||
- Steps to reproduce the issue
|
||||
- Potential impact assessment
|
||||
- Any suggested fixes (if available)
|
||||
|
||||
### What to Expect
|
||||
|
||||
- **Acknowledgment**: We'll acknowledge receipt of your report within 48 hours
|
||||
- **Investigation**: We'll investigate and validate the report within 5 business days
|
||||
- **Resolution**: We'll work on a fix and coordinate disclosure timeline
|
||||
- **Credit**: We'll credit you in the security advisory (unless you prefer to remain anonymous)
|
||||
|
||||
## Security Measures
|
||||
|
||||
### Automated Security Scanning
|
||||
|
||||
We employ multiple layers of automated security scanning:
|
||||
|
||||
- **govulncheck**: Go-specific vulnerability scanning
|
||||
- **Trivy**: Container and filesystem security scanning
|
||||
- **gitleaks**: Secrets detection and prevention
|
||||
- **CodeQL**: Static code analysis
|
||||
- **Dependabot**: Automated dependency updates
|
||||
|
||||
### Secure Development Practices
|
||||
|
||||
- All dependencies are regularly updated
|
||||
- Security patches are prioritized
|
||||
- Code is reviewed by maintainers
|
||||
- CI/CD pipelines include security checks
|
||||
- Container images are scanned for vulnerabilities
|
||||
|
||||
### Supply Chain Security
|
||||
|
||||
- Dependencies are pinned to specific versions
|
||||
- SBOM (Software Bill of Materials) is generated for releases
|
||||
- Artifacts are signed using Cosign
|
||||
- Docker images are built with minimal attack surface
|
||||
|
||||
## Security Configuration
|
||||
|
||||
### For Users
|
||||
|
||||
When using gh-action-readme in your projects:
|
||||
|
||||
1. **Keep Updated**: Always use the latest version
|
||||
2. **Review Permissions**: Only grant necessary GitHub token permissions
|
||||
3. **Validate Inputs**: Sanitize any user-provided inputs
|
||||
4. **Monitor Dependencies**: Use Dependabot or similar tools
|
||||
|
||||
### For Contributors
|
||||
|
||||
When contributing to gh-action-readme:
|
||||
|
||||
1. **Follow Security Guidelines**: See [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
2. **Run Security Scans**: Use `make security` before submitting PRs
|
||||
3. **Handle Secrets Carefully**: Never commit secrets or API keys
|
||||
4. **Update Dependencies**: Keep dependencies current and secure
|
||||
|
||||
## Known Security Considerations
|
||||
|
||||
### GitHub Token Usage
|
||||
|
||||
gh-action-readme requires GitHub API access for dependency analysis:
|
||||
|
||||
- Uses read-only operations when possible
|
||||
- Respects rate limits to prevent abuse
|
||||
- Caches results to minimize API calls
|
||||
- Never stores or logs authentication tokens
|
||||
|
||||
### Template Processing
|
||||
|
||||
Template rendering includes security measures:
|
||||
|
||||
- Input sanitization for user-provided data
|
||||
- No execution of arbitrary code
|
||||
- Limited template functions to prevent injection
|
||||
|
||||
## Security Tools and Commands
|
||||
|
||||
### Local Security Testing
|
||||
|
||||
```bash
|
||||
# Run all security scans
|
||||
make security
|
||||
|
||||
# Individual scans
|
||||
make vulncheck # Go vulnerability check
|
||||
make trivy # Filesystem scanning
|
||||
make gitleaks # Secrets detection
|
||||
|
||||
# Security audit
|
||||
make audit # Comprehensive dependency audit
|
||||
```
|
||||
|
||||
### CI/CD Security
|
||||
|
||||
Our GitHub Actions workflows automatically run:
|
||||
|
||||
- Security scans on every PR and push
|
||||
- Weekly scheduled vulnerability checks
|
||||
- Dependency reviews for pull requests
|
||||
- Container image security scanning
|
||||
|
||||
## Security Best Practices for Users
|
||||
|
||||
### GitHub Actions Usage
|
||||
|
||||
```yaml
|
||||
# Recommended secure usage
|
||||
- name: Generate README
|
||||
uses: ivuorinen/gh-action-readme@v1
|
||||
with:
|
||||
github-token: ${{ secrets.GITHUB_TOKEN }}
|
||||
# Limit token permissions in workflow
|
||||
permissions:
|
||||
contents: read
|
||||
metadata: read
|
||||
```
|
||||
|
||||
### Local Development
|
||||
|
||||
```bash
|
||||
# Install security tools
|
||||
go install golang.org/x/vuln/cmd/govulncheck@latest
|
||||
# Install trivy: https://aquasecurity.github.io/trivy/
|
||||
# Install gitleaks: https://github.com/gitleaks/gitleaks
|
||||
|
||||
# Run before committing
|
||||
make security
|
||||
```
|
||||
|
||||
## Incident Response
|
||||
|
||||
In case of a security incident:
|
||||
|
||||
1. **Immediate Response**: Assess and contain the issue
|
||||
2. **Communication**: Notify affected users through security advisories
|
||||
3. **Remediation**: Release patches and updated documentation
|
||||
4. **Post-Incident**: Review and improve security measures
|
||||
|
||||
## Security Contact
|
||||
|
||||
For security-related questions or concerns:
|
||||
|
||||
- **Email**: [security@ivuorinen.dev](mailto:security@ivuorinen.dev)
|
||||
- **PGP Key**: Available upon request
|
||||
- **Response Time**: Within 48 hours for security issues
|
||||
|
||||
---
|
||||
|
||||
*This security policy is reviewed quarterly and updated as needed to reflect current best practices and threat landscape.*
|
||||
397
docs/themes.md
Normal file
397
docs/themes.md
Normal file
@@ -0,0 +1,397 @@
|
||||
# Themes
|
||||
|
||||
gh-action-readme includes 5 built-in themes, each optimized for different use cases and visual preferences.
|
||||
|
||||
## 🎨 Available Themes
|
||||
|
||||
### GitHub Theme
|
||||
|
||||
**Best for:** GitHub Marketplace actions, open source projects
|
||||
|
||||
```bash
|
||||
gh-action-readme gen --theme github
|
||||
```
|
||||
|
||||
**Features:**
|
||||
|
||||
- GitHub-style badges and shields
|
||||
- Collapsible sections for better organization
|
||||
- Table-based parameter documentation
|
||||
- Action marketplace optimization
|
||||
- GitHub-specific styling and layout
|
||||
|
||||
**Example output:**
|
||||
|
||||
- ✅ Professional badges
|
||||
- 📊 Clean input/output tables
|
||||
- 🔧 Copy-paste usage examples
|
||||
- 📁 Collapsible troubleshooting sections
|
||||
|
||||
### GitLab Theme
|
||||
|
||||
**Best for:** GitLab CI/CD integration, GitLab-hosted projects
|
||||
|
||||
```bash
|
||||
gh-action-readme gen --theme gitlab
|
||||
```
|
||||
|
||||
**Features:**
|
||||
|
||||
- GitLab CI/CD pipeline examples
|
||||
- GitLab-specific badge integration
|
||||
- Pipeline configuration snippets
|
||||
- GitLab Pages optimization
|
||||
|
||||
### Minimal Theme
|
||||
|
||||
**Best for:** Simple actions, lightweight documentation
|
||||
|
||||
```bash
|
||||
gh-action-readme gen --theme minimal
|
||||
```
|
||||
|
||||
**Features:**
|
||||
|
||||
- Clean, distraction-free layout
|
||||
- Essential information only
|
||||
- Faster loading and parsing
|
||||
- Mobile-friendly design
|
||||
- Minimal dependencies
|
||||
|
||||
### Professional Theme
|
||||
|
||||
**Best for:** Enterprise actions, comprehensive documentation
|
||||
|
||||
```bash
|
||||
gh-action-readme gen --theme professional
|
||||
```
|
||||
|
||||
**Features:**
|
||||
|
||||
- Comprehensive table of contents
|
||||
- Detailed troubleshooting sections
|
||||
- Advanced usage examples
|
||||
- Security and compliance notes
|
||||
- Enterprise-ready formatting
|
||||
|
||||
### Default Theme
|
||||
|
||||
**Best for:** Basic needs, backward compatibility
|
||||
|
||||
```bash
|
||||
gh-action-readme gen --theme default
|
||||
```
|
||||
|
||||
**Features:**
|
||||
|
||||
- Original simple template
|
||||
- Basic parameter documentation
|
||||
- Minimal formatting
|
||||
- Guaranteed compatibility
|
||||
|
||||
## 🎯 Theme Comparison
|
||||
|
||||
| Feature | GitHub | GitLab | Minimal | Professional | Default |
|
||||
|---------|--------|--------|---------|-------------|---------|
|
||||
| **Badges** | ✅ Rich | ✅ GitLab | ❌ None | ✅ Comprehensive | ❌ None |
|
||||
| **TOC** | ✅ Yes | ✅ Yes | ❌ No | ✅ Advanced | ❌ No |
|
||||
| **Examples** | ✅ GitHub | ✅ CI/CD | ✅ Basic | ✅ Comprehensive | ✅ Basic |
|
||||
| **Troubleshooting** | ✅ Collapsible | ✅ Pipeline | ❌ Minimal | ✅ Detailed | ❌ None |
|
||||
| **File Size** | Medium | Medium | Small | Large | Small |
|
||||
| **Load Time** | Fast | Fast | Fastest | Slower | Fast |
|
||||
|
||||
## 🛠️ Theme Examples
|
||||
|
||||
### Input Action
|
||||
|
||||
```yaml
|
||||
name: Deploy to AWS
|
||||
description: Deploy application to AWS using GitHub Actions
|
||||
inputs:
|
||||
aws-region:
|
||||
description: AWS region to deploy to
|
||||
required: true
|
||||
default: us-east-1
|
||||
environment:
|
||||
description: Deployment environment
|
||||
required: false
|
||||
default: production
|
||||
outputs:
|
||||
deployment-url:
|
||||
description: URL of the deployed application
|
||||
runs:
|
||||
using: composite
|
||||
steps:
|
||||
- run: echo "Deploying to AWS..."
|
||||
```
|
||||
|
||||
### GitHub Theme Output
|
||||
|
||||
```markdown
|
||||
# Deploy to AWS
|
||||
|
||||
[](https://github.com/marketplace)
|
||||
|
||||
> Deploy application to AWS using GitHub Actions
|
||||
|
||||
## 🚀 Usage
|
||||
|
||||
```yaml
|
||||
- uses: your-org/deploy-aws@v1
|
||||
with:
|
||||
aws-region: us-west-2
|
||||
environment: staging
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary>📋 Inputs</summary>
|
||||
|
||||
| Input | Description | Required | Default |
|
||||
|-------|-------------|----------|---------|
|
||||
| `aws-region` | AWS region to deploy to | Yes | `us-east-1` |
|
||||
| `environment` | Deployment environment | No | `production` |
|
||||
|
||||
</details>
|
||||
```
|
||||
|
||||
### Minimal Theme Output
|
||||
|
||||
```markdown
|
||||
# Deploy to AWS
|
||||
|
||||
Deploy application to AWS using GitHub Actions
|
||||
|
||||
## Usage
|
||||
|
||||
```yaml
|
||||
- uses: your-org/deploy-aws@v1
|
||||
with:
|
||||
aws-region: us-west-2
|
||||
```
|
||||
|
||||
## Inputs
|
||||
|
||||
- `aws-region` (required): AWS region to deploy to
|
||||
- `environment` (optional): Deployment environment (default: production)
|
||||
|
||||
## Outputs
|
||||
|
||||
- `deployment-url`: URL of the deployed application
|
||||
|
||||
```text
|
||||
|
||||
## 🎨 Custom Themes
|
||||
|
||||
### Creating Custom Themes
|
||||
|
||||
1. **Copy existing theme:**
|
||||
```bash
|
||||
cp -r templates/themes/github templates/themes/my-theme
|
||||
```
|
||||
|
||||
1. **Edit template files:**
|
||||
|
||||
```bash
|
||||
# Main template
|
||||
vim templates/themes/my-theme/readme.tmpl
|
||||
|
||||
# Optional partials
|
||||
vim templates/themes/my-theme/partials/header.tmpl
|
||||
```
|
||||
|
||||
1. **Use custom theme:**
|
||||
|
||||
```bash
|
||||
gh-action-readme gen --theme my-theme
|
||||
```
|
||||
|
||||
### Theme Structure
|
||||
|
||||
```text
|
||||
templates/themes/my-theme/
|
||||
├── readme.tmpl # Main template (required)
|
||||
├── partials/ # Partial templates (optional)
|
||||
│ ├── header.tmpl # Header section
|
||||
│ ├── inputs.tmpl # Inputs table
|
||||
│ ├── outputs.tmpl # Outputs table
|
||||
│ ├── examples.tmpl # Usage examples
|
||||
│ └── footer.tmpl # Footer section
|
||||
└── assets/ # Theme assets (optional)
|
||||
├── styles.css # Custom CSS
|
||||
└── images/ # Theme images
|
||||
```
|
||||
|
||||
### Template Variables
|
||||
|
||||
Available variables in templates:
|
||||
|
||||
```go
|
||||
type ActionData struct {
|
||||
Name string // Action name
|
||||
Description string // Action description
|
||||
Inputs map[string]ActionInput // Input parameters
|
||||
Outputs map[string]ActionOutput // Output parameters
|
||||
Runs map[string]interface{} // Runs configuration
|
||||
Branding *Branding // Branding info
|
||||
|
||||
// Enhanced data
|
||||
Repository *Repository // GitHub repo info
|
||||
Dependencies []Dependency // Analyzed dependencies
|
||||
Examples []Example // Usage examples
|
||||
}
|
||||
```
|
||||
|
||||
### Template Functions
|
||||
|
||||
Built-in template functions:
|
||||
|
||||
```go
|
||||
// String functions
|
||||
{{ .Name | title }} // Title case
|
||||
{{ .Description | truncate 100 }} // Truncate to 100 chars
|
||||
{{ .Name | slug }} // URL-friendly slug
|
||||
|
||||
// Formatting functions
|
||||
{{ .Inputs | toTable }} // Generate input table
|
||||
{{ .Dependencies | toList }} // Generate dependency list
|
||||
{{ .Examples | toYAML }} // Format as YAML
|
||||
|
||||
// Conditional functions
|
||||
{{ if hasInputs }}...{{ end }} // Check if inputs exist
|
||||
{{ if .Branding }}...{{ end }} // Check if branding exists
|
||||
```
|
||||
|
||||
### Advanced Template Example
|
||||
|
||||
```go-template
|
||||
{{/* Custom theme header */}}
|
||||
# {{ .Name }}
|
||||
|
||||
{{ if .Branding }}
|
||||
<p align="center">
|
||||
<img src="{{ .Branding.Icon }}" alt="{{ .Name }}" width="64">
|
||||
</p>
|
||||
{{ end }}
|
||||
|
||||
> {{ .Description }}
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
```yaml
|
||||
- uses: {{ .Repository.FullName }}@{{ .Repository.DefaultBranch }}
|
||||
with:
|
||||
{{- range $key, $input := .Inputs }}
|
||||
{{- if $input.Required }}
|
||||
{{ $key }}: # {{ $input.Description }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
```
|
||||
|
||||
{{ if .Inputs }}
|
||||
|
||||
## 📋 Configuration
|
||||
|
||||
{{ template "inputs-table" . }}
|
||||
{{ end }}
|
||||
|
||||
{{ if .Dependencies }}
|
||||
|
||||
## 🔗 Dependencies
|
||||
|
||||
This action uses the following dependencies:
|
||||
{{ range .Dependencies }}
|
||||
|
||||
- [{{ .Name }}]({{ .SourceURL }}) - {{ .Description }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
|
||||
{{/*Include footer partial if it exists*/}}
|
||||
{{ template "footer" . }}
|
||||
|
||||
```go-template
|
||||
|
||||
## 🔧 Theme Configuration
|
||||
|
||||
### Set Default Theme
|
||||
```bash
|
||||
# Set globally
|
||||
gh-action-readme config set theme professional
|
||||
|
||||
# Use environment variable
|
||||
export GH_ACTION_README_THEME=github
|
||||
```
|
||||
|
||||
### Theme-Specific Settings
|
||||
|
||||
```yaml
|
||||
# ~/.config/gh-action-readme/config.yaml
|
||||
theme: github
|
||||
theme_settings:
|
||||
github:
|
||||
show_badges: true
|
||||
collapse_sections: true
|
||||
show_toc: true
|
||||
minimal:
|
||||
show_examples: true
|
||||
compact_tables: true
|
||||
professional:
|
||||
detailed_examples: true
|
||||
show_troubleshooting: true
|
||||
```
|
||||
|
||||
### Dynamic Theme Selection
|
||||
|
||||
```bash
|
||||
# Select theme based on repository type
|
||||
if [[ -f ".gitlab-ci.yml" ]]; then
|
||||
gh-action-readme gen --theme gitlab
|
||||
elif [[ -f "package.json" ]]; then
|
||||
gh-action-readme gen --theme github
|
||||
else
|
||||
gh-action-readme gen --theme minimal
|
||||
fi
|
||||
```
|
||||
|
||||
## 📱 Responsive Design
|
||||
|
||||
All themes support responsive design:
|
||||
|
||||
- **Desktop**: Full-width tables and detailed sections
|
||||
- **Tablet**: Condensed tables with horizontal scrolling
|
||||
- **Mobile**: Stacked layouts and collapsible sections
|
||||
|
||||
## 🎨 Theme Customization Tips
|
||||
|
||||
### Colors and Styling
|
||||
|
||||
```css
|
||||
/* Custom CSS for HTML output */
|
||||
.action-header { color: #0366d6; }
|
||||
.input-table { border-collapse: collapse; }
|
||||
.example-code { background: #f6f8fa; }
|
||||
```
|
||||
|
||||
### Badge Customization
|
||||
|
||||
```go-template
|
||||
{{/* Custom badges */}}
|
||||
|
||||
|
||||
|
||||
```
|
||||
|
||||
### Conditional Content
|
||||
|
||||
```go-template
|
||||
{{/* Show different content based on action type */}}
|
||||
{{ if eq .Runs.Using "composite" }}
|
||||
## Composite Action Steps
|
||||
{{ range .Runs.Steps }}
|
||||
- {{ .Name }}: {{ .Run }}
|
||||
{{ end }}
|
||||
{{ else if eq .Runs.Using "docker" }}
|
||||
## Docker Configuration
|
||||
- Image: `{{ .Runs.Image }}`
|
||||
- Args: `{{ join .Runs.Args " " }}`
|
||||
{{ end }}
|
||||
```
|
||||
247
docs/usage.md
Normal file
247
docs/usage.md
Normal file
@@ -0,0 +1,247 @@
|
||||
# Usage Guide
|
||||
|
||||
Comprehensive guide to using gh-action-readme for generating documentation from GitHub Actions.
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
Generate documentation from your action.yml:
|
||||
|
||||
```bash
|
||||
# Basic generation
|
||||
gh-action-readme gen
|
||||
|
||||
# With specific theme and output
|
||||
gh-action-readme gen --theme github --output README.md
|
||||
```
|
||||
|
||||
## 📋 Examples
|
||||
|
||||
### Input: `action.yml`
|
||||
|
||||
```yaml
|
||||
name: My Action
|
||||
description: Does something awesome
|
||||
inputs:
|
||||
token:
|
||||
description: GitHub token
|
||||
required: true
|
||||
environment:
|
||||
description: Target environment
|
||||
default: production
|
||||
outputs:
|
||||
result:
|
||||
description: Action result
|
||||
runs:
|
||||
using: node20
|
||||
main: index.js
|
||||
```
|
||||
|
||||
### Output: Professional README.md
|
||||
|
||||
The tool generates comprehensive documentation including:
|
||||
|
||||
- 📊 **Parameter tables** with types, requirements, defaults
|
||||
- 💡 **Usage examples** with proper YAML formatting
|
||||
- 🎨 **Badges** for marketplace visibility
|
||||
- 📚 **Multiple sections** (Overview, Configuration, Examples, Troubleshooting)
|
||||
- 🔗 **Navigation** with table of contents
|
||||
|
||||
## 🛠️ Commands
|
||||
|
||||
### Generation
|
||||
|
||||
```bash
|
||||
gh-action-readme gen [directory_or_file] [flags]
|
||||
-f, --output-format string md, html, json, asciidoc (default "md")
|
||||
-o, --output-dir string output directory (default ".")
|
||||
--output string custom output filename
|
||||
-t, --theme string github, gitlab, minimal, professional
|
||||
-r, --recursive search recursively
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Generate with GitHub theme
|
||||
gh-action-readme gen --theme github
|
||||
|
||||
# Generate HTML documentation
|
||||
gh-action-readme gen --output-format html
|
||||
|
||||
# Process specific directory
|
||||
gh-action-readme gen actions/checkout/
|
||||
|
||||
# Custom output filename
|
||||
gh-action-readme gen --output my-action-docs.md
|
||||
|
||||
# Recursive processing
|
||||
gh-action-readme gen --recursive --theme professional
|
||||
```
|
||||
|
||||
### Validation
|
||||
|
||||
```bash
|
||||
gh-action-readme validate
|
||||
|
||||
# With verbose output
|
||||
gh-action-readme validate --verbose
|
||||
```
|
||||
|
||||
**Example Output:**
|
||||
|
||||
```text
|
||||
❌ Missing required field: description
|
||||
💡 Add 'description: Brief description of what your action does'
|
||||
|
||||
✅ All inputs have descriptions
|
||||
⚠️ Consider adding 'branding' section for marketplace visibility
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
```bash
|
||||
gh-action-readme config init # Create default config
|
||||
gh-action-readme config show # Show current settings
|
||||
gh-action-readme config themes # List available themes
|
||||
gh-action-readme config wizard # Interactive configuration
|
||||
```
|
||||
|
||||
## 🎯 Advanced Usage
|
||||
|
||||
### Batch Processing
|
||||
|
||||
```bash
|
||||
# Process multiple repositories with custom outputs
|
||||
find . -name "action.yml" -execdir gh-action-readme gen --theme github --output README-generated.md \;
|
||||
|
||||
# Recursive processing with JSON output
|
||||
gh-action-readme gen --recursive --output-format json --output-dir docs/
|
||||
|
||||
# Target multiple specific actions
|
||||
gh-action-readme gen actions/checkout/ --theme github --output docs/checkout.md
|
||||
gh-action-readme gen actions/setup-node/ --theme professional --output docs/setup-node.md
|
||||
```
|
||||
|
||||
### Custom Templates
|
||||
|
||||
```bash
|
||||
# Copy and modify existing theme
|
||||
cp -r templates/themes/github templates/themes/custom
|
||||
# Edit templates/themes/custom/readme.tmpl
|
||||
gh-action-readme gen --theme custom
|
||||
```
|
||||
|
||||
### Environment Integration
|
||||
|
||||
```bash
|
||||
# Set default preferences
|
||||
export GH_ACTION_README_THEME=github
|
||||
export GH_ACTION_README_VERBOSE=true
|
||||
export GITHUB_TOKEN=your_token_here
|
||||
|
||||
# Use with different output formats
|
||||
gh-action-readme gen --output-format html --output docs/index.html
|
||||
gh-action-readme gen --output-format json --output api/action.json
|
||||
```
|
||||
|
||||
## 📄 Output Formats
|
||||
|
||||
| Format | Description | Use Case | Extension |
|
||||
|--------|-------------|----------|-----------|
|
||||
| **md** | Markdown (default) | GitHub README files | `.md` |
|
||||
| **html** | Styled HTML | Web documentation | `.html` |
|
||||
| **json** | Structured data | API integration | `.json` |
|
||||
| **asciidoc** | AsciiDoc format | Technical docs | `.adoc` |
|
||||
|
||||
### Format Examples
|
||||
|
||||
```bash
|
||||
# Markdown (default)
|
||||
gh-action-readme gen --output-format md
|
||||
|
||||
# HTML with custom styling
|
||||
gh-action-readme gen --output-format html --output docs/action.html
|
||||
|
||||
# JSON for API consumption
|
||||
gh-action-readme gen --output-format json --output api/metadata.json
|
||||
|
||||
# AsciiDoc for technical documentation
|
||||
gh-action-readme gen --output-format asciidoc --output docs/action.adoc
|
||||
```
|
||||
|
||||
## 🎨 Themes
|
||||
|
||||
See [themes.md](themes.md) for detailed theme documentation.
|
||||
|
||||
| Theme | Best For | Features |
|
||||
|-------|----------|----------|
|
||||
| **github** | GitHub marketplace | Badges, collapsible sections |
|
||||
| **gitlab** | GitLab repositories | CI/CD examples |
|
||||
| **minimal** | Simple actions | Clean, concise |
|
||||
| **professional** | Enterprise use | Comprehensive docs |
|
||||
| **default** | Basic needs | Original template |
|
||||
|
||||
## ⚙️ Configuration
|
||||
|
||||
See [configuration.md](configuration.md) for detailed configuration options.
|
||||
|
||||
## 🔧 Testing Generation
|
||||
|
||||
**Safe testing with sample data:**
|
||||
|
||||
```bash
|
||||
# Test with included examples (safe - won't overwrite)
|
||||
gh-action-readme gen testdata/example-action/ --theme github --output test-output.md
|
||||
gh-action-readme gen testdata/composite-action/action.yml --theme professional
|
||||
|
||||
# Test all themes
|
||||
for theme in github gitlab minimal professional default; do
|
||||
gh-action-readme gen testdata/example-action/ --theme $theme --output "test-${theme}.md"
|
||||
done
|
||||
|
||||
# Test all formats
|
||||
for format in md html json asciidoc; do
|
||||
gh-action-readme gen testdata/example-action/ --output-format $format --output "test.${format}"
|
||||
done
|
||||
```
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**File not found:**
|
||||
|
||||
```bash
|
||||
# Make sure action.yml exists in current directory or specify path
|
||||
gh-action-readme gen path/to/action.yml
|
||||
```
|
||||
|
||||
**Permission errors:**
|
||||
|
||||
```bash
|
||||
# Check file permissions
|
||||
ls -la action.yml
|
||||
chmod 644 action.yml
|
||||
```
|
||||
|
||||
**GitHub API rate limits:**
|
||||
|
||||
```bash
|
||||
# Set GitHub token for higher rate limits
|
||||
export GITHUB_TOKEN=your_token_here
|
||||
gh-action-readme gen --verbose
|
||||
```
|
||||
|
||||
**Template errors:**
|
||||
|
||||
```bash
|
||||
# Validate your action.yml first
|
||||
gh-action-readme validate --verbose
|
||||
```
|
||||
|
||||
### Getting Help
|
||||
|
||||
1. Run with `--verbose` flag for detailed output
|
||||
2. Check [GitHub Issues](https://github.com/ivuorinen/gh-action-readme/issues)
|
||||
3. Validate your action.yml syntax
|
||||
4. Verify file permissions and paths
|
||||
Reference in New Issue
Block a user