From c55c4b4459ec7847c83365825e9eabb6743987fc Mon Sep 17 00:00:00 2001 From: Ho Ngoc Hai Date: Sun, 18 Jan 2026 23:12:29 +0700 Subject: [PATCH] docs: Add new documentation references for automation tools and configuration guidelines. --- .../documentation/references/AUTOMATION.md | 123 ++++++++++++++ .../documentation/references/CONFIGURATION.md | 153 ++++++++++++++++++ 2 files changed, 276 insertions(+) create mode 100644 .agent/skills/documentation/references/AUTOMATION.md create mode 100644 .agent/skills/documentation/references/CONFIGURATION.md diff --git a/.agent/skills/documentation/references/AUTOMATION.md b/.agent/skills/documentation/references/AUTOMATION.md new file mode 100644 index 00000000..5c424e08 --- /dev/null +++ b/.agent/skills/documentation/references/AUTOMATION.md @@ -0,0 +1,123 @@ +# Automation & Tools / Công Cụ Tự Động + +This reference provides tools and scripts for automating documentation validation and generation. + +## Link Checking + +Validate all markdown links to prevent broken references: + +```bash +# Install markdown-link-check +npm install -g markdown-link-check + +# Check single file +markdown-link-check docs/en/README.md + +# Check all markdown files in docs/ +find docs -name "*.md" | xargs markdown-link-check + +# With config file +markdown-link-check -c .markdown-link-check.json docs/en/README.md +``` + +**Config example** (`.markdown-link-check.json`): +```json +{ + "ignorePatterns": [ + { "pattern": "^http://localhost" }, + { "pattern": "^https://api.goodgo.vn" } + ], + "timeout": "20s", + "retryOn429": true, + "aliveStatusCodes": [200, 206] +} +``` + +## Markdown Linting + +Enforce consistent markdown style: + +```bash +# Install markdownlint-cli +npm install -g markdownlint-cli + +# Lint all docs +markdownlint docs/**/*.md + +# Fix auto-fixable issues +markdownlint --fix docs/**/*.md + +# With config +markdownlint -c .markdownlint.json docs/**/*.md +``` + +**Config example** (`.markdownlint.json`): +```json +{ + "default": true, + "MD013": { "line_length": 120 }, + "MD033": false, + "MD041": false +} +``` + +## Documentation Generation + +**OpenAPI to Markdown:** +```bash +# Using redoc-cli +npx @redocly/cli build-docs docs/en/api/openapi/service.yaml \ + -o docs/en/api/reference.html + +# Using swagger-markdown +npx swagger-markdown -i docs/en/api/openapi/service.yaml \ + -o docs/en/api/REFERENCE.md +``` + +**C# XML Comments to Markdown:** +```bash +# Using xmldoc2md (for .NET projects) +dotnet tool install -g xmldoc2md +xmldoc2md src/MyService.API/bin/Debug/net8.0/MyService.API.xml \ + docs/en/api/ +``` + +## CI/CD Integration + +```yaml +# .github/workflows/docs-validation.yml +name: Validate Documentation + +on: [pull_request] + +jobs: + validate-docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Check links + run: | + npm install -g markdown-link-check + find docs -name "*.md" | xargs markdown-link-check + - name: Lint markdown + run: | + npm install -g markdownlint-cli + markdownlint docs/**/*.md +``` + +## Documentation Testing + +```bash +# Check for broken links +find docs -name "*.md" -exec markdown-link-check {} \; + +# Lint markdown files +markdownlint docs/**/*.md +``` + +## Resources + +- [markdown-link-check](https://github.com/tcort/markdown-link-check) - Validate markdown links +- [markdownlint](https://github.com/DavidAnson/markdownlint) - Markdown linter +- [Redocly CLI](https://redocly.com/docs/cli/) - OpenAPI tools +- [Back to Documentation Skill](../SKILL.md) diff --git a/.agent/skills/documentation/references/CONFIGURATION.md b/.agent/skills/documentation/references/CONFIGURATION.md new file mode 100644 index 00000000..dab4abe5 --- /dev/null +++ b/.agent/skills/documentation/references/CONFIGURATION.md @@ -0,0 +1,153 @@ +# Configuration Documentation / Tài Liệu Cấu Hình + +This reference provides templates and guidelines for documenting service configuration. + +## Environment Variables Table + +```markdown +## Environment Variables / Biến Môi Trường + +### Required Variables / Biến Bắt Buộc + +| Variable | Type | Description / Mô Tả | Example | +|----------|------|---------------------|----------| +| `DATABASE_URL` | string | PostgreSQL connection string / Chuỗi kết nối PostgreSQL | `postgresql://user:pass@localhost:5432/db` | +| `REDIS_URL` | string | Redis connection string / Chuỗi kết nối Redis | `redis://localhost:6379` | +| `JWT_SECRET` | string | Secret key for JWT signing / Khóa bí mật ký JWT | `your-256-bit-secret` | +| `RABBITMQ_URL` | string | RabbitMQ connection / Kết nối RabbitMQ | `amqp://user:pass@localhost:5672` | + +### Optional Variables / Biến Tùy Chọn + +| Variable | Type | Description / Mô Tả | Default | +|----------|------|---------------------|----------| +| `PORT` | integer | Server port / Cổng server | `5000` | +| `LOG_LEVEL` | enum | Logging level: `debug`, `info`, `warn`, `error` | `info` | +| `CORS_ORIGINS` | string | Allowed CORS origins (comma-separated) | `*` | +| `RATE_LIMIT_MAX` | integer | Max requests per window / Số request tối đa | `100` | +| `RATE_LIMIT_WINDOW_MS` | integer | Rate limit window in ms / Cửa sổ giới hạn (ms) | `60000` | +| `CACHE_TTL_SECONDS` | integer | Default cache TTL / TTL cache mặc định | `300` | +``` + +## Configuration File Example + +```markdown +## Configuration File: `appsettings.json` + +\`\`\`json +{ + "Server": { + "Port": 5000, + "Environment": "Development", + "EnableSwagger": true + }, + "Database": { + "Host": "localhost", + "Port": 5432, + "Name": "goodgo_dev", + "Username": "postgres", + "Password": "password", + "MaxPoolSize": 20, + "CommandTimeout": 30 + }, + "Redis": { + "Host": "localhost", + "Port": 6379, + "Database": 0, + "Password": null, + "ConnectTimeout": 5000, + "SyncTimeout": 5000 + }, + "Jwt": { + "Secret": "your-secret-key-min-32-chars", + "Issuer": "goodgo-platform", + "Audience": "goodgo-clients", + "ExpirationMinutes": 60, + "RefreshTokenExpirationDays": 7 + }, + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft": "Warning", + "Microsoft.Hosting.Lifetime": "Information" + }, + "Console": { + "FormatterName": "json" + } + }, + "RateLimiting": { + "PermitLimit": 100, + "Window": "00:01:00", + "QueueLimit": 10 + }, + "Cors": { + "AllowedOrigins": [ + "http://localhost:3000", + "https://app.goodgo.vn" + ], + "AllowCredentials": true, + "AllowedHeaders": ["*"], + "AllowedMethods": ["GET", "POST", "PUT", "DELETE"] + } +} +\`\`\` + +**Notes:** +- **EN**: Never commit secrets to version control. Use environment variables or secret management tools. +- **VI**: Không bao giờ commit secrets vào version control. Dùng biến môi trường hoặc công cụ quản lý secrets. +``` + +## Docker Compose Configuration + +```markdown +## Docker Compose Configuration + +\`\`\`yaml +version: '3.8' + +services: + app: + build: . + ports: + - "5000:5000" + environment: + - DATABASE_URL=postgresql://postgres:password@db:5432/goodgo + - REDIS_URL=redis://redis:6379 + - JWT_SECRET=${JWT_SECRET} + - LOG_LEVEL=info + depends_on: + - db + - redis + + db: + image: postgres:15 + environment: + - POSTGRES_DB=goodgo + - POSTGRES_USER=postgres + - POSTGRES_PASSWORD=password + volumes: + - postgres_data:/var/lib/postgresql/data + ports: + - "5432:5432" + + redis: + image: redis:7-alpine + ports: + - "6379:6379" + volumes: + - redis_data:/data + +volumes: + postgres_data: + redis_data: +\`\`\` + +**Environment File** (`.env`): +\`\`\`bash +JWT_SECRET=your-production-secret-key-min-32-characters +DATABASE_PASSWORD=your-secure-db-password +\`\`\` +``` + +## Resources + +- [Back to Documentation Skill](../SKILL.md)