mirror of
https://github.com/ivuorinen/gh-action-readme.git
synced 2026-02-11 08:48:22 +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
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
|
||||
```
|
||||
Reference in New Issue
Block a user