From 856f48d9f631378093c1668484f23eecfaa94f00 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 16 Oct 2025 00:28:22 +0000 Subject: [PATCH 1/5] Initial plan From b5b1a95229fa3a73c3ef93ce813bf8aff9bc27d3 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 16 Oct 2025 00:38:02 +0000 Subject: [PATCH 2/5] Implement documentation publishing services system Co-authored-by: Shivansh9000 <15914113+Shivansh9000@users.noreply.github.com> --- README.md | 74 ++- docs-publishing-service/ARCHITECTURE.md | 412 +++++++++++++ docs-publishing-service/README.md | 139 +++++ docs-publishing-service/api/README.md | 292 ++++++++++ docs-publishing-service/api/openapi.yaml | 551 ++++++++++++++++++ docs-publishing-service/config/README.md | 62 ++ .../config/brands/example-brand/config.yaml | 141 +++++ .../config/brands/example-brand/styles.css | 282 +++++++++ .../brands/example-brand/validation.yaml | 223 +++++++ docs-publishing-service/config/default.yaml | 160 +++++ docs-publishing-service/examples/README.md | 300 ++++++++++ docs-publishing-service/templates/README.md | 125 ++++ docs-publishing-service/templates/standard.md | 139 +++++ docs-publishing-service/templates/tutorial.md | 229 ++++++++ docs-publishing-service/workflows/README.md | 286 +++++++++ .../workflows/publish-docs.yml | 225 +++++++ 16 files changed, 3639 insertions(+), 1 deletion(-) create mode 100644 docs-publishing-service/ARCHITECTURE.md create mode 100644 docs-publishing-service/README.md create mode 100644 docs-publishing-service/api/README.md create mode 100644 docs-publishing-service/api/openapi.yaml create mode 100644 docs-publishing-service/config/README.md create mode 100644 docs-publishing-service/config/brands/example-brand/config.yaml create mode 100644 docs-publishing-service/config/brands/example-brand/styles.css create mode 100644 docs-publishing-service/config/brands/example-brand/validation.yaml create mode 100644 docs-publishing-service/config/default.yaml create mode 100644 docs-publishing-service/examples/README.md create mode 100644 docs-publishing-service/templates/README.md create mode 100644 docs-publishing-service/templates/standard.md create mode 100644 docs-publishing-service/templates/tutorial.md create mode 100644 docs-publishing-service/workflows/README.md create mode 100644 docs-publishing-service/workflows/publish-docs.yml diff --git a/README.md b/README.md index 53b8bd3..ba16bf0 100644 --- a/README.md +++ b/README.md @@ -1 +1,73 @@ -# .github-private \ No newline at end of file +# .github-private + +## Documentation Publishing Services + +This repository contains the **Documentation Publishing Services** - an intermediary service system that brings coherence, uniformity, and provides a better managed knowledge base platform for brand-endorsed documentation. + +### Features + +- 📝 **Universal Documentation Publishing** - Publish documentation from any format to brand-endorsed platforms +- ✅ **Validation & Quality Assurance** - Automated validation ensuring documentation meets brand standards +- 🔄 **Format Transformation** - Convert between multiple documentation formats seamlessly +- 🎨 **Brand Consistency** - Apply brand-specific styling and guidelines automatically +- 🤖 **Automation Ready** - GitHub Actions workflows for CI/CD integration +- 📊 **Multi-Brand Support** - Manage documentation for multiple brands from one system + +### Quick Start + +See the [Documentation Publishing Service README](./docs-publishing-service/README.md) for complete documentation. + +#### Publishing a Document + +```bash +curl -X POST https://api.docs-publishing.example.com/v1/publish \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "source": "path/to/document.md", + "brand": "your-brand", + "category": "guides" + }' +``` + +#### Using GitHub Actions + +```yaml +name: Publish Documentation +on: + push: + paths: ['docs/**'] + +jobs: + publish: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: ./docs-publishing-service/workflows/publish-action +``` + +### Documentation + +- 📖 [Main Documentation](./docs-publishing-service/README.md) +- 🏗️ [Architecture Overview](./docs-publishing-service/ARCHITECTURE.md) +- 🔌 [API Reference](./docs-publishing-service/api/README.md) +- ⚙️ [Configuration Guide](./docs-publishing-service/config/README.md) +- 📋 [Templates](./docs-publishing-service/templates/README.md) +- 🔄 [Workflows](./docs-publishing-service/workflows/README.md) +- 💡 [Examples](./docs-publishing-service/examples/README.md) + +### Repository Structure + +``` +.github-private/ +├── docs-publishing-service/ +│ ├── api/ # API specifications +│ ├── config/ # Configuration files +│ │ └── brands/ # Brand-specific configs +│ ├── templates/ # Documentation templates +│ ├── workflows/ # GitHub Actions workflows +│ ├── examples/ # Usage examples +│ ├── README.md # Service documentation +│ └── ARCHITECTURE.md # Architecture details +├── README.md # This file +└── LICENSE \ No newline at end of file diff --git a/docs-publishing-service/ARCHITECTURE.md b/docs-publishing-service/ARCHITECTURE.md new file mode 100644 index 0000000..20d72d7 --- /dev/null +++ b/docs-publishing-service/ARCHITECTURE.md @@ -0,0 +1,412 @@ +# Architecture Documentation + +## System Overview + +The Documentation Publishing Service is an intermediary service designed to standardize, validate, and publish documentation across multiple brands and platforms. It acts as a centralized knowledge base management system that ensures consistency and quality. + +## Design Principles + +1. **Brand Agnostic**: Support multiple brands with different styling and guidelines +2. **Format Flexibility**: Accept various input formats and produce multiple outputs +3. **Quality First**: Enforce validation and standards before publishing +4. **API-Driven**: RESTful API for integration with any workflow +5. **Automation Ready**: GitHub Actions and CI/CD integration +6. **Extensible**: Plugin architecture for custom validators and transformers + +## High-Level Architecture + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Content Sources │ +│ (Markdown, HTML, RST, Wiki, CMS, Developer Docs) │ +└─────────────────┬───────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Ingestion Layer │ +│ - Format Detection │ +│ - Content Extraction │ +│ - Metadata Parsing │ +└─────────────────┬───────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Validation Layer │ +│ - Structure Validation │ +│ - Content Quality Checks │ +│ - Brand Guidelines Enforcement │ +│ - Accessibility Checks │ +└─────────────────┬───────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Transformation Layer │ +│ - Format Conversion (via Pandoc) │ +│ - Style Application │ +│ - Template Rendering │ +│ - Asset Processing │ +└─────────────────┬───────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Publishing Layer │ +│ - Version Management │ +│ - Distribution to Destinations │ +│ - Index/Search Updates │ +│ - Cache Invalidation │ +└─────────────────┬───────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Publishing Destinations │ +│ (Static Sites, Confluence, SharePoint, S3, CDN) │ +└─────────────────────────────────────────────────────────────┘ +``` + +## Core Components + +### 1. API Service + +**Purpose**: RESTful API for all documentation operations + +**Responsibilities**: +- Receive documentation submissions +- Authenticate and authorize requests +- Route requests to appropriate handlers +- Return responses with status and validation results + +**Technology Stack**: +- Language: Node.js, Python, or Go +- Framework: Express.js, FastAPI, or Gin +- Authentication: JWT tokens or API keys +- Rate Limiting: Redis-backed limiter + +**Endpoints**: +- `POST /v1/publish` - Publish new document +- `GET /v1/documents` - List documents +- `GET /v1/documents/{id}` - Get document +- `PUT /v1/documents/{id}` - Update document +- `DELETE /v1/documents/{id}` - Delete document +- `POST /v1/validate` - Validate document +- `POST /v1/transform` - Transform format +- `GET /v1/brands` - List brands +- `GET /v1/brands/{id}/config` - Get brand config + +### 2. Validation Engine + +**Purpose**: Ensure documentation meets quality and brand standards + +**Components**: +- **Structure Validator**: Check document structure and sections +- **Content Validator**: Analyze content quality and readability +- **Style Validator**: Enforce brand style guidelines +- **Technical Validator**: Verify code examples and links +- **Accessibility Validator**: Ensure WCAG compliance + +**Validation Pipeline**: +1. Parse document and extract metadata +2. Run structural checks +3. Analyze content quality +4. Check style guidelines +5. Validate technical accuracy +6. Generate validation report + +**Configurable Rules**: +- Per-brand rule sets +- Global baseline rules +- Custom validation plugins + +### 3. Transformation Engine + +**Purpose**: Convert between formats and apply styling + +**Capabilities**: +- Format conversion (Markdown ↔ HTML ↔ RST ↔ PDF) +- Template application +- Style injection +- Asset optimization +- Table of contents generation +- Cross-referencing + +**Technology**: +- Pandoc for format conversion +- Template engines (Jinja2, Handlebars) +- CSS processors for styling +- Image optimization libraries + +### 4. Brand Configuration Manager + +**Purpose**: Manage brand-specific settings and rules + +**Configuration Hierarchy**: +``` +Global Defaults + ↓ +Brand Configuration + ↓ +Document Metadata + ↓ +Runtime Options +``` + +**Brand Settings**: +- Style guidelines +- Validation rules +- Template preferences +- Publishing destinations +- Integration configurations + +### 5. Storage Layer + +**Purpose**: Store and version documentation + +**Storage Options**: +- **Filesystem**: Local or network storage +- **Object Storage**: S3, GCS, Azure Blob +- **Database**: PostgreSQL, MongoDB for metadata +- **Git**: Version control integration + +**Versioning**: +- Full version history +- Diff capabilities +- Rollback support +- Branch/tag support + +### 6. Publishing Pipeline + +**Purpose**: Deploy documentation to destinations + +**Stages**: +1. **Pre-publish**: Run final validations +2. **Build**: Generate output formats +3. **Stage**: Deploy to staging environment +4. **Review**: Optional manual approval +5. **Publish**: Deploy to production +6. **Post-publish**: Update indexes, clear caches + +**Destinations**: +- Static site generators (Hugo, Jekyll) +- Wiki systems (Confluence, MediaWiki) +- CDN deployment +- Documentation platforms (ReadTheDocs) + +### 7. Workflow Orchestrator + +**Purpose**: Coordinate multi-step processes + +**Workflows**: +- Ingestion → Validation → Transformation → Publishing +- Scheduled updates and maintenance +- Batch processing +- Rollback procedures + +**Integration**: +- GitHub Actions +- Jenkins +- GitLab CI +- Custom webhooks + +### 8. Notification Service + +**Purpose**: Alert stakeholders of events + +**Events**: +- Document published +- Validation failed +- Review required +- Publishing error + +**Channels**: +- Email +- Slack +- Microsoft Teams +- Webhooks +- SMS (for critical alerts) + +## Data Flow + +### Publishing Flow + +``` +1. User submits document + ↓ +2. API receives and queues request + ↓ +3. Validation engine processes document + ↓ (if validation passes) +4. Transformation engine converts format + ↓ +5. Brand styling applied + ↓ +6. Assets processed and optimized + ↓ +7. Document stored with version + ↓ +8. Publishing pipeline deploys + ↓ +9. Notifications sent + ↓ +10. Response returned to user +``` + +### Validation Flow + +``` +1. Document received + ↓ +2. Parse frontmatter and extract metadata + ↓ +3. Run structural validation + ↓ +4. Analyze content quality + ↓ +5. Check against brand guidelines + ↓ +6. Verify technical elements + ↓ +7. Compile validation report + ↓ +8. Return results with score +``` + +## Security Considerations + +### Authentication & Authorization + +- API key-based authentication +- JWT tokens for session management +- Role-based access control (RBAC) +- Brand-level permissions + +### Data Security + +- Encrypt sensitive data at rest +- Use HTTPS for all API communications +- Sanitize HTML input to prevent XSS +- Validate and escape all user input + +### Rate Limiting + +- Per-API-key rate limits +- Burst handling +- DDoS protection +- Graceful degradation + +## Scalability + +### Horizontal Scaling + +- Stateless API servers +- Load balancing +- Distributed caching (Redis) +- Queue-based processing + +### Performance Optimization + +- Document caching +- CDN for static assets +- Lazy loading +- Batch operations +- Background jobs for heavy processing + +### Monitoring + +- API metrics (latency, throughput) +- Error tracking +- Resource utilization +- Validation success rates +- Publishing statistics + +## Integration Points + +### Version Control Systems + +- **GitHub**: Actions, API integration +- **GitLab**: CI/CD pipelines +- **Bitbucket**: Webhooks + +### Documentation Platforms + +- **Confluence**: REST API +- **SharePoint**: Graph API +- **ReadTheDocs**: Webhook triggers + +### Communication Tools + +- **Slack**: Incoming webhooks +- **Microsoft Teams**: Connectors +- **Email**: SMTP + +### Analytics + +- **Google Analytics**: Page views, engagement +- **Mixpanel**: User behavior +- **Custom**: Search queries, popular docs + +## Deployment Architecture + +### Development Environment + +``` +Local Development +├── API Server (port 8080) +├── Redis (port 6379) +├── PostgreSQL (port 5432) +└── File storage (./data) +``` + +### Production Environment + +``` +Load Balancer + ↓ +API Servers (Auto-scaled) + ↓ +├── Cache Layer (Redis Cluster) +├── Database (PostgreSQL Primary + Replicas) +├── Object Storage (S3) +└── Queue System (RabbitMQ/SQS) +``` + +### High Availability + +- Multiple availability zones +- Database replication +- Automated backups +- Disaster recovery procedures +- Health checks and auto-recovery + +## Future Enhancements + +1. **AI-Powered Features** + - Automatic summarization + - Smart tagging + - Content recommendations + - Quality scoring + +2. **Enhanced Collaboration** + - Real-time editing + - Comment threads + - Approval workflows + - Change tracking + +3. **Advanced Analytics** + - Content gap analysis + - User engagement metrics + - Search analytics + - Performance dashboards + +4. **Localization** + - Multi-language support + - Translation workflows + - Locale-specific validation + +5. **Integration Expansion** + - More CMS platforms + - Additional notification channels + - Enhanced API capabilities + - Plugin marketplace + +## Conclusion + +This architecture provides a robust, scalable foundation for managing documentation across multiple brands. The modular design allows for incremental improvements and adaptations to changing requirements while maintaining consistency and quality standards. diff --git a/docs-publishing-service/README.md b/docs-publishing-service/README.md new file mode 100644 index 0000000..5173aa1 --- /dev/null +++ b/docs-publishing-service/README.md @@ -0,0 +1,139 @@ +# Documentation Publishing Services + +An intermediary service that brings coherence, uniformity, and provides a better managed knowledge base platform for brand-endorsed documentation. + +## Overview + +The Documentation Publishing Services is a comprehensive system designed to standardize, validate, and publish documentation across multiple brands and platforms. It acts as an intermediary layer that ensures all documentation meets brand standards and maintains consistency. + +## Architecture + +``` +┌─────────────────┐ +│ Source Docs │ +│ (Any Format) │ +└────────┬────────┘ + │ + ▼ +┌─────────────────┐ +│ Intermediary │ +│ Service │ +│ - Validation │ +│ - Transform │ +│ - Standardize │ +└────────┬────────┘ + │ + ▼ +┌─────────────────┐ +│ Brand-Endorsed │ +│ Documentation │ +│ Knowledge Base │ +└─────────────────┘ +``` + +## Features + +- **Universal Input Support**: Accept documentation in various formats (Markdown, HTML, reStructuredText, etc.) +- **Standardization**: Automatically apply brand guidelines and formatting standards +- **Validation**: Ensure documentation meets quality and consistency requirements +- **Transformation**: Convert between different documentation formats +- **Publishing Workflow**: Automated pipeline for documentation deployment +- **Version Control**: Track changes and maintain documentation history +- **Multi-Brand Support**: Support different brand guidelines and styling + +## Components + +### 1. API Service +RESTful API for submitting and managing documentation + +### 2. Configuration +Brand-specific configuration and styling rules + +### 3. Templates +Standardized templates for different documentation types + +### 4. Workflows +Automated GitHub Actions workflows for CI/CD + +### 5. Examples +Sample documentation and usage examples + +## Quick Start + +### Publishing a Document + +```bash +# Submit a document for publishing +curl -X POST https://api.docs-publishing.example.com/v1/publish \ + -H "Content-Type: application/json" \ + -d '{ + "source": "path/to/document.md", + "brand": "your-brand", + "category": "guides", + "metadata": { + "title": "Getting Started Guide", + "author": "Documentation Team", + "version": "1.0.0" + } + }' +``` + +### Using GitHub Actions + +```yaml +name: Publish Documentation +on: + push: + paths: + - 'docs/**' + +jobs: + publish: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: ./docs-publishing-service/workflows/publish-action + with: + brand: your-brand + source-dir: docs/ +``` + +## Configuration + +Brand-specific configurations are stored in `config/brands/`. Each brand has: + +- Style guidelines +- Template overrides +- Validation rules +- Publishing destinations + +## Directory Structure + +``` +docs-publishing-service/ +├── api/ # API specifications and schemas +├── config/ # Configuration files +│ └── brands/ # Brand-specific configs +├── templates/ # Documentation templates +├── workflows/ # GitHub Actions workflows +├── examples/ # Usage examples +└── README.md # This file +``` + +## API Reference + +See [API Documentation](./api/README.md) for detailed API reference. + +## Contributing + +1. Submit documentation following the guidelines in `templates/` +2. Ensure all validations pass +3. Follow the brand guidelines in `config/brands/` + +## Support + +For issues or questions, please open an issue in the repository. + +## License + +See LICENSE file for details. diff --git a/docs-publishing-service/api/README.md b/docs-publishing-service/api/README.md new file mode 100644 index 0000000..efb90df --- /dev/null +++ b/docs-publishing-service/api/README.md @@ -0,0 +1,292 @@ +# Documentation Publishing API + +RESTful API for the Documentation Publishing Service. + +## Base URL + +``` +https://api.docs-publishing.example.com/v1 +``` + +## Authentication + +All API requests require authentication using an API key: + +``` +Authorization: Bearer YOUR_API_KEY +``` + +## Endpoints + +### POST /publish + +Submit a document for publishing. + +**Request Body:** + +```json +{ + "source": "string", // Path or URL to source document + "content": "string", // Alternative: direct content + "format": "markdown", // Source format: markdown, html, rst, etc. + "brand": "string", // Brand identifier + "category": "string", // Documentation category + "metadata": { + "title": "string", + "author": "string", + "version": "string", + "tags": ["string"], + "description": "string" + }, + "options": { + "validate": true, // Run validation before publishing + "transform": true, // Apply transformations + "publish": true // Publish immediately or draft + } +} +``` + +**Response:** + +```json +{ + "id": "string", + "status": "pending|processing|published|failed", + "url": "string", + "validations": { + "passed": boolean, + "errors": ["string"], + "warnings": ["string"] + }, + "published_at": "timestamp", + "version": "string" +} +``` + +### GET /documents/{id} + +Retrieve a published document. + +**Response:** + +```json +{ + "id": "string", + "title": "string", + "content": "string", + "format": "string", + "brand": "string", + "category": "string", + "metadata": {}, + "status": "string", + "created_at": "timestamp", + "updated_at": "timestamp", + "published_at": "timestamp", + "version": "string" +} +``` + +### PUT /documents/{id} + +Update an existing document. + +**Request Body:** Same as POST /publish + +**Response:** Same as POST /publish + +### DELETE /documents/{id} + +Delete a published document. + +**Response:** + +```json +{ + "id": "string", + "status": "deleted" +} +``` + +### GET /documents + +List all documents with optional filtering. + +**Query Parameters:** +- `brand` - Filter by brand +- `category` - Filter by category +- `status` - Filter by status +- `page` - Page number +- `limit` - Items per page + +**Response:** + +```json +{ + "documents": [ + { + "id": "string", + "title": "string", + "brand": "string", + "category": "string", + "status": "string", + "published_at": "timestamp" + } + ], + "pagination": { + "page": 1, + "limit": 20, + "total": 100, + "pages": 5 + } +} +``` + +### POST /validate + +Validate a document without publishing. + +**Request Body:** + +```json +{ + "content": "string", + "format": "string", + "brand": "string", + "rules": ["string"] // Optional: specific validation rules +} +``` + +**Response:** + +```json +{ + "valid": boolean, + "errors": [ + { + "line": number, + "column": number, + "message": "string", + "rule": "string", + "severity": "error|warning" + } + ], + "warnings": [], + "score": number // 0-100 quality score +} +``` + +### POST /transform + +Transform a document from one format to another. + +**Request Body:** + +```json +{ + "content": "string", + "from": "markdown", + "to": "html", + "options": { + "brand": "string", + "apply_styles": true, + "include_toc": true + } +} +``` + +**Response:** + +```json +{ + "content": "string", + "format": "string", + "metadata": {} +} +``` + +### GET /brands + +List available brands and their configurations. + +**Response:** + +```json +{ + "brands": [ + { + "id": "string", + "name": "string", + "description": "string", + "categories": ["string"], + "formats": ["string"] + } + ] +} +``` + +### GET /brands/{brand}/config + +Get configuration for a specific brand. + +**Response:** + +```json +{ + "brand": "string", + "styles": {}, + "validation_rules": [], + "templates": [], + "categories": [] +} +``` + +## Error Responses + +All errors follow this format: + +```json +{ + "error": { + "code": "string", + "message": "string", + "details": {} + } +} +``` + +**Common Error Codes:** +- `400` - Bad Request +- `401` - Unauthorized +- `403` - Forbidden +- `404` - Not Found +- `422` - Unprocessable Entity (validation failed) +- `500` - Internal Server Error + +## Rate Limiting + +- 100 requests per minute per API key +- Rate limit headers included in all responses: + - `X-RateLimit-Limit` + - `X-RateLimit-Remaining` + - `X-RateLimit-Reset` + +## Webhooks + +Subscribe to events: + +- `document.published` +- `document.updated` +- `document.deleted` +- `validation.failed` + +Configure webhooks in your brand settings. + +## SDK Support + +Official SDKs available for: +- JavaScript/Node.js +- Python +- Go +- Ruby + +See [examples/](../examples/) for usage examples. diff --git a/docs-publishing-service/api/openapi.yaml b/docs-publishing-service/api/openapi.yaml new file mode 100644 index 0000000..a3a6d9d --- /dev/null +++ b/docs-publishing-service/api/openapi.yaml @@ -0,0 +1,551 @@ +openapi: 3.0.3 +info: + title: Documentation Publishing Service API + description: API for publishing and managing brand-endorsed documentation + version: 1.0.0 + contact: + name: Documentation Team + email: docs@example.com + +servers: + - url: https://api.docs-publishing.example.com/v1 + description: Production server + - url: https://api-staging.docs-publishing.example.com/v1 + description: Staging server + +security: + - BearerAuth: [] + +paths: + /publish: + post: + summary: Publish a document + operationId: publishDocument + tags: + - Documents + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/PublishRequest' + responses: + '201': + description: Document published successfully + content: + application/json: + schema: + $ref: '#/components/schemas/PublishResponse' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '422': + $ref: '#/components/responses/ValidationError' + + /documents: + get: + summary: List documents + operationId: listDocuments + tags: + - Documents + parameters: + - name: brand + in: query + schema: + type: string + - name: category + in: query + schema: + type: string + - name: status + in: query + schema: + type: string + enum: [draft, published, archived] + - name: page + in: query + schema: + type: integer + default: 1 + - name: limit + in: query + schema: + type: integer + default: 20 + maximum: 100 + responses: + '200': + description: List of documents + content: + application/json: + schema: + $ref: '#/components/schemas/DocumentList' + + /documents/{id}: + get: + summary: Get a document + operationId: getDocument + tags: + - Documents + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + '200': + description: Document details + content: + application/json: + schema: + $ref: '#/components/schemas/Document' + '404': + $ref: '#/components/responses/NotFound' + + put: + summary: Update a document + operationId: updateDocument + tags: + - Documents + parameters: + - name: id + in: path + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/PublishRequest' + responses: + '200': + description: Document updated successfully + content: + application/json: + schema: + $ref: '#/components/schemas/PublishResponse' + + delete: + summary: Delete a document + operationId: deleteDocument + tags: + - Documents + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + '200': + description: Document deleted + content: + application/json: + schema: + type: object + properties: + id: + type: string + status: + type: string + enum: [deleted] + + /validate: + post: + summary: Validate a document + operationId: validateDocument + tags: + - Validation + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ValidateRequest' + responses: + '200': + description: Validation result + content: + application/json: + schema: + $ref: '#/components/schemas/ValidationResult' + + /transform: + post: + summary: Transform a document + operationId: transformDocument + tags: + - Transform + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/TransformRequest' + responses: + '200': + description: Transformed document + content: + application/json: + schema: + $ref: '#/components/schemas/TransformResponse' + + /brands: + get: + summary: List available brands + operationId: listBrands + tags: + - Brands + responses: + '200': + description: List of brands + content: + application/json: + schema: + $ref: '#/components/schemas/BrandList' + + /brands/{brand}/config: + get: + summary: Get brand configuration + operationId: getBrandConfig + tags: + - Brands + parameters: + - name: brand + in: path + required: true + schema: + type: string + responses: + '200': + description: Brand configuration + content: + application/json: + schema: + $ref: '#/components/schemas/BrandConfig' + +components: + securitySchemes: + BearerAuth: + type: http + scheme: bearer + bearerFormat: JWT + + schemas: + PublishRequest: + type: object + required: + - brand + - metadata + properties: + source: + type: string + description: Path or URL to source document + content: + type: string + description: Direct content (alternative to source) + format: + type: string + enum: [markdown, html, rst, asciidoc, latex] + default: markdown + brand: + type: string + description: Brand identifier + category: + type: string + description: Documentation category + metadata: + $ref: '#/components/schemas/DocumentMetadata' + options: + $ref: '#/components/schemas/PublishOptions' + + PublishOptions: + type: object + properties: + validate: + type: boolean + default: true + transform: + type: boolean + default: true + publish: + type: boolean + default: true + + DocumentMetadata: + type: object + required: + - title + properties: + title: + type: string + author: + type: string + version: + type: string + tags: + type: array + items: + type: string + description: + type: string + + PublishResponse: + type: object + properties: + id: + type: string + status: + type: string + enum: [pending, processing, published, failed] + url: + type: string + validations: + $ref: '#/components/schemas/ValidationResult' + published_at: + type: string + format: date-time + version: + type: string + + Document: + type: object + properties: + id: + type: string + title: + type: string + content: + type: string + format: + type: string + brand: + type: string + category: + type: string + metadata: + $ref: '#/components/schemas/DocumentMetadata' + status: + type: string + created_at: + type: string + format: date-time + updated_at: + type: string + format: date-time + published_at: + type: string + format: date-time + version: + type: string + + DocumentList: + type: object + properties: + documents: + type: array + items: + type: object + properties: + id: + type: string + title: + type: string + brand: + type: string + category: + type: string + status: + type: string + published_at: + type: string + format: date-time + pagination: + $ref: '#/components/schemas/Pagination' + + Pagination: + type: object + properties: + page: + type: integer + limit: + type: integer + total: + type: integer + pages: + type: integer + + ValidateRequest: + type: object + required: + - content + - brand + properties: + content: + type: string + format: + type: string + default: markdown + brand: + type: string + rules: + type: array + items: + type: string + + ValidationResult: + type: object + properties: + valid: + type: boolean + errors: + type: array + items: + $ref: '#/components/schemas/ValidationError' + warnings: + type: array + items: + $ref: '#/components/schemas/ValidationError' + score: + type: number + minimum: 0 + maximum: 100 + + ValidationError: + type: object + properties: + line: + type: integer + column: + type: integer + message: + type: string + rule: + type: string + severity: + type: string + enum: [error, warning, info] + + TransformRequest: + type: object + required: + - content + - from + - to + properties: + content: + type: string + from: + type: string + enum: [markdown, html, rst, asciidoc, latex] + to: + type: string + enum: [markdown, html, rst, asciidoc, latex, pdf] + options: + type: object + properties: + brand: + type: string + apply_styles: + type: boolean + include_toc: + type: boolean + + TransformResponse: + type: object + properties: + content: + type: string + format: + type: string + metadata: + type: object + + BrandList: + type: object + properties: + brands: + type: array + items: + type: object + properties: + id: + type: string + name: + type: string + description: + type: string + categories: + type: array + items: + type: string + formats: + type: array + items: + type: string + + BrandConfig: + type: object + properties: + brand: + type: string + styles: + type: object + validation_rules: + type: array + items: + type: string + templates: + type: array + items: + type: string + categories: + type: array + items: + type: string + + Error: + type: object + properties: + error: + type: object + properties: + code: + type: string + message: + type: string + details: + type: object + + responses: + BadRequest: + description: Bad request + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + Unauthorized: + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + NotFound: + description: Not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + ValidationError: + description: Validation error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' diff --git a/docs-publishing-service/config/README.md b/docs-publishing-service/config/README.md new file mode 100644 index 0000000..0cb9677 --- /dev/null +++ b/docs-publishing-service/config/README.md @@ -0,0 +1,62 @@ +# Configuration + +Configuration files for the Documentation Publishing Service. + +## Structure + +``` +config/ +├── brands/ # Brand-specific configurations +│ ├── example-brand/ +│ │ ├── config.yaml +│ │ ├── styles.css +│ │ └── validation.yaml +│ └── README.md +├── default.yaml # Default service configuration +└── validation-rules.yaml # Global validation rules +``` + +## Brand Configuration + +Each brand has its own directory under `brands/` containing: + +### config.yaml +Brand metadata and general settings: +- Brand name and identifier +- Supported categories +- Publishing destinations +- Template preferences + +### styles.css +Brand-specific styling for documentation: +- Colors and typography +- Layout preferences +- Component styling + +### validation.yaml +Brand-specific validation rules: +- Required sections +- Formatting requirements +- Quality standards +- Terminology guidelines + +## Default Configuration + +The `default.yaml` file contains service-wide defaults that apply when brand-specific settings are not provided. + +## Validation Rules + +Global validation rules in `validation-rules.yaml` apply to all brands unless overridden in brand-specific configurations. + +## Usage + +Brands are automatically detected from the directory structure. To add a new brand: + +1. Create a new directory under `brands/` +2. Add `config.yaml` with required settings +3. Optionally add `styles.css` and `validation.yaml` +4. The service will automatically recognize the new brand + +## Example + +See `brands/example-brand/` for a complete example configuration. diff --git a/docs-publishing-service/config/brands/example-brand/config.yaml b/docs-publishing-service/config/brands/example-brand/config.yaml new file mode 100644 index 0000000..95bae06 --- /dev/null +++ b/docs-publishing-service/config/brands/example-brand/config.yaml @@ -0,0 +1,141 @@ +# Example Brand Configuration + +brand: + id: "example-brand" + name: "Example Brand" + description: "Example brand configuration for documentation publishing" + website: "https://example-brand.com" + contact_email: "docs@example-brand.com" + +# Brand-specific settings +settings: + # Supported documentation categories + categories: + - getting-started + - user-guides + - developer-guides + - api-reference + - tutorials + - best-practices + - troubleshooting + - release-notes + + # Preferred formats + input_formats: + - markdown + - html + + output_formats: + - html + - pdf + + # Publishing destinations + destinations: + - type: "static-site" + url: "https://docs.example-brand.com" + path: "/published" + - type: "confluence" + space: "DOCS" + parent_page: "Documentation" + +# Styling preferences +styling: + theme: "light" + primary_color: "#007bff" + secondary_color: "#6c757d" + font_family: "Inter, sans-serif" + code_font: "Fira Code, monospace" + + layout: + max_width: "1200px" + sidebar: true + toc: true + breadcrumbs: true + +# Brand guidelines +guidelines: + tone: "professional" + voice: "active" + perspective: "second-person" # Use "you" instead of "the user" + + # Terminology preferences + terminology: + - prefer: "documentation" + avoid: "docs" + - prefer: "click" + avoid: "click on" + - prefer: "sign in" + avoid: "login" + +# Validation overrides +validation: + strict_mode: true + min_quality_score: 80 + + required_sections: + - title + - overview + - prerequisites + + custom_rules: + - no_passive_voice + - consistent_terminology + - proper_code_formatting + +# Template preferences +templates: + default: "standard" + available: + - standard + - tutorial + - api-reference + - troubleshooting + +# Metadata requirements +metadata: + required: + - title + - author + - category + - version + + auto_generate: + - last_updated + - word_count + - reading_time + +# Publishing workflow +workflow: + review_required: true + approval_required: true + reviewers: + - docs-team + + stages: + - validate + - review + - approve + - publish + +# Webhooks +webhooks: + - event: "document.published" + url: "https://example-brand.com/webhooks/docs-published" + - event: "document.updated" + url: "https://example-brand.com/webhooks/docs-updated" + +# Integration settings +integrations: + github: + enabled: true + org: "example-brand" + repo: "documentation" + + slack: + enabled: true + channel: "#documentation" + + analytics: + enabled: true + provider: "google-analytics" + tracking_id: "UA-XXXXXXXXX-X" diff --git a/docs-publishing-service/config/brands/example-brand/styles.css b/docs-publishing-service/config/brands/example-brand/styles.css new file mode 100644 index 0000000..429a8ba --- /dev/null +++ b/docs-publishing-service/config/brands/example-brand/styles.css @@ -0,0 +1,282 @@ +/* Example Brand Documentation Styles */ + +:root { + /* Brand colors */ + --brand-primary: #007bff; + --brand-secondary: #6c757d; + --brand-success: #28a745; + --brand-danger: #dc3545; + --brand-warning: #ffc107; + --brand-info: #17a2b8; + + /* Typography */ + --font-family-base: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; + --font-family-code: 'Fira Code', 'Courier New', monospace; + --font-size-base: 16px; + --line-height-base: 1.6; + + /* Spacing */ + --spacing-xs: 0.25rem; + --spacing-sm: 0.5rem; + --spacing-md: 1rem; + --spacing-lg: 1.5rem; + --spacing-xl: 2rem; + + /* Layout */ + --max-content-width: 1200px; + --sidebar-width: 280px; + --header-height: 64px; +} + +/* Base styles */ +body { + font-family: var(--font-family-base); + font-size: var(--font-size-base); + line-height: var(--line-height-base); + color: #333; + background-color: #fff; + margin: 0; + padding: 0; +} + +/* Typography */ +h1, h2, h3, h4, h5, h6 { + font-weight: 600; + line-height: 1.3; + margin-top: var(--spacing-xl); + margin-bottom: var(--spacing-md); + color: #1a1a1a; +} + +h1 { + font-size: 2.5rem; + border-bottom: 2px solid var(--brand-primary); + padding-bottom: var(--spacing-sm); +} + +h2 { + font-size: 2rem; + border-bottom: 1px solid #e0e0e0; + padding-bottom: var(--spacing-xs); +} + +h3 { + font-size: 1.5rem; +} + +h4 { + font-size: 1.25rem; +} + +p { + margin-bottom: var(--spacing-md); +} + +a { + color: var(--brand-primary); + text-decoration: none; +} + +a:hover { + text-decoration: underline; +} + +/* Code blocks */ +code { + font-family: var(--font-family-code); + font-size: 0.9em; + background-color: #f5f5f5; + padding: 0.2em 0.4em; + border-radius: 3px; + color: #d63384; +} + +pre { + background-color: #f8f9fa; + border: 1px solid #e0e0e0; + border-radius: 4px; + padding: var(--spacing-md); + overflow-x: auto; + margin-bottom: var(--spacing-md); +} + +pre code { + background-color: transparent; + padding: 0; + color: inherit; +} + +/* Lists */ +ul, ol { + margin-bottom: var(--spacing-md); + padding-left: var(--spacing-xl); +} + +li { + margin-bottom: var(--spacing-xs); +} + +/* Tables */ +table { + width: 100%; + border-collapse: collapse; + margin-bottom: var(--spacing-md); +} + +th, td { + padding: var(--spacing-sm) var(--spacing-md); + text-align: left; + border: 1px solid #e0e0e0; +} + +th { + background-color: #f8f9fa; + font-weight: 600; + color: #1a1a1a; +} + +tr:nth-child(even) { + background-color: #fafafa; +} + +/* Blockquotes */ +blockquote { + border-left: 4px solid var(--brand-primary); + padding-left: var(--spacing-md); + margin-left: 0; + color: #666; + font-style: italic; +} + +/* Images */ +img { + max-width: 100%; + height: auto; + border-radius: 4px; +} + +/* Callouts */ +.callout { + padding: var(--spacing-md); + border-radius: 4px; + margin-bottom: var(--spacing-md); + border-left: 4px solid; +} + +.callout-info { + background-color: #e7f3ff; + border-color: var(--brand-info); +} + +.callout-warning { + background-color: #fff3cd; + border-color: var(--brand-warning); +} + +.callout-danger { + background-color: #f8d7da; + border-color: var(--brand-danger); +} + +.callout-success { + background-color: #d4edda; + border-color: var(--brand-success); +} + +/* Layout */ +.doc-container { + max-width: var(--max-content-width); + margin: 0 auto; + padding: var(--spacing-md); +} + +.doc-header { + border-bottom: 1px solid #e0e0e0; + padding-bottom: var(--spacing-md); + margin-bottom: var(--spacing-xl); +} + +.doc-content { + line-height: var(--line-height-base); +} + +.doc-footer { + border-top: 1px solid #e0e0e0; + padding-top: var(--spacing-md); + margin-top: var(--spacing-xl); + color: #666; + font-size: 0.9em; +} + +/* Table of contents */ +.toc { + background-color: #f8f9fa; + border: 1px solid #e0e0e0; + border-radius: 4px; + padding: var(--spacing-md); + margin-bottom: var(--spacing-md); +} + +.toc-title { + font-weight: 600; + margin-bottom: var(--spacing-sm); +} + +.toc ul { + list-style: none; + padding-left: var(--spacing-md); +} + +/* Buttons */ +.btn { + display: inline-block; + padding: var(--spacing-sm) var(--spacing-md); + background-color: var(--brand-primary); + color: white; + border: none; + border-radius: 4px; + cursor: pointer; + text-align: center; + text-decoration: none; + font-size: 1rem; +} + +.btn:hover { + background-color: #0056b3; + text-decoration: none; +} + +/* Responsive */ +@media (max-width: 768px) { + :root { + --font-size-base: 14px; + } + + h1 { + font-size: 2rem; + } + + h2 { + font-size: 1.5rem; + } + + .doc-container { + padding: var(--spacing-sm); + } +} + +/* Print styles */ +@media print { + .no-print { + display: none; + } + + a[href]:after { + content: " (" attr(href) ")"; + } + + pre, code { + border: 1px solid #999; + page-break-inside: avoid; + } +} diff --git a/docs-publishing-service/config/brands/example-brand/validation.yaml b/docs-publishing-service/config/brands/example-brand/validation.yaml new file mode 100644 index 0000000..38e6fdb --- /dev/null +++ b/docs-publishing-service/config/brands/example-brand/validation.yaml @@ -0,0 +1,223 @@ +# Validation Rules for Example Brand + +# General validation settings +validation: + strict: true + fail_on_warnings: false + min_quality_score: 80 + +# Content structure rules +structure: + required_sections: + - name: "Title" + pattern: "^# .+" + description: "Document must have a level 1 heading" + + - name: "Overview" + keywords: ["overview", "introduction", "about"] + description: "Document should include an overview section" + + - name: "Prerequisites" + keywords: ["prerequisites", "requirements", "before you begin"] + description: "Document should list prerequisites if applicable" + optional: true + + section_order: + - title + - overview + - prerequisites + - content + - next_steps + - related + +# Content quality rules +quality: + # Minimum content length + min_words: 100 + max_words: 10000 + + # Reading level + readability: + enabled: true + target_score: 60 # Flesch reading ease + max_grade_level: 12 + + # Spelling and grammar + spelling: + enabled: true + dictionary: "en_US" + custom_words: + - "Example Brand" + - "ExampleBrand" + + grammar: + enabled: true + check_passive_voice: true + max_passive_percentage: 10 + +# Formatting rules +formatting: + # Headings + headings: + max_length: 80 + capitalization: "title" # title, sentence, lower, upper + no_trailing_punctuation: true + sequential_levels: true # No skipping heading levels + + # Lists + lists: + consistent_markers: true + proper_indentation: true + + # Code blocks + code_blocks: + require_language: true + max_length: 50 # lines + + # Links + links: + check_validity: true + no_broken_links: true + prefer_https: true + require_title: false + + # Images + images: + require_alt_text: true + check_existence: true + max_size: "2MB" + allowed_formats: ["png", "jpg", "jpeg", "gif", "svg"] + +# Style guide rules +style: + # Tone and voice + tone: + - rule: "use_active_voice" + description: "Prefer active voice over passive voice" + severity: "warning" + + - rule: "second_person" + description: "Use second person (you) instead of third person (the user)" + severity: "warning" + + - rule: "present_tense" + description: "Use present tense when possible" + severity: "info" + + # Word choice + word_choice: + forbidden_words: + - word: "simply" + reason: "Implies something is easy, which may not be true for all users" + - word: "just" + reason: "Can be condescending" + - word: "obviously" + reason: "Assumes knowledge" + - word: "easy" + reason: "Subjective and potentially discouraging" + + preferred_terms: + - prefer: "click" + avoid: "click on" + - prefer: "sign in" + avoid: ["login", "log in"] + - prefer: "user name" + avoid: "username" + - prefer: "email" + avoid: "e-mail" + + # Punctuation + punctuation: + oxford_comma: true + space_after_period: 1 + no_multiple_punctuation: true + consistent_quotes: "double" # double or single + +# Technical accuracy rules +technical: + # Code examples + code_examples: + require_testing: false + include_comments: true + follow_style_guide: true + + # API references + api_references: + include_parameters: true + include_return_values: true + include_examples: true + + # Version information + versioning: + include_version: true + date_format: "YYYY-MM-DD" + +# Accessibility rules +accessibility: + # Alt text for images + images: + require_alt: true + alt_max_length: 150 + + # Link text + links: + descriptive_text: true + no_click_here: true + + # Color contrast + colors: + check_contrast: true + min_contrast_ratio: 4.5 + +# Brand-specific rules +brand: + # Terminology + terminology: + - term: "Example Brand" + description: "Always capitalize both words" + pattern: "Example Brand" + incorrect: ["example brand", "Example brand", "example Brand"] + + # Product names + products: + - name: "Example Product" + description: "Official product name" + always_capitalize: true + + # Trademark usage + trademarks: + include_symbol: true + first_use_only: true + +# Custom validation rules +custom_rules: + - id: "no-lorem-ipsum" + pattern: "lorem ipsum" + message: "Remove placeholder text" + severity: "error" + + - id: "no-todo" + pattern: "TODO|FIXME|XXX" + message: "Resolve all TODO comments before publishing" + severity: "error" + + - id: "proper-date-format" + pattern: '\d{4}-\d{2}-\d{2}' + message: "Use ISO date format (YYYY-MM-DD)" + severity: "warning" + +# Exceptions +exceptions: + # Files or sections that skip certain rules + skip_validation: + - path: "examples/**" + rules: ["min_words", "readability"] + + - path: "api-reference/**" + rules: ["tone", "word_choice"] + +# Reporting +reporting: + format: "detailed" # detailed, summary, json + include_suggestions: true + group_by_severity: true diff --git a/docs-publishing-service/config/default.yaml b/docs-publishing-service/config/default.yaml new file mode 100644 index 0000000..e68bddc --- /dev/null +++ b/docs-publishing-service/config/default.yaml @@ -0,0 +1,160 @@ +# Default Configuration for Documentation Publishing Service + +service: + name: "Documentation Publishing Service" + version: "1.0.0" + api_version: "v1" + +# Server settings +server: + host: "0.0.0.0" + port: 8080 + timeout: 30s + max_request_size: 10MB + +# Publishing defaults +publishing: + default_format: markdown + supported_formats: + - markdown + - html + - rst + - asciidoc + - latex + + output_formats: + - html + - pdf + - markdown + + default_options: + validate: true + transform: true + publish: true + include_toc: true + apply_styles: true + +# Validation defaults +validation: + enabled: true + strict_mode: false + min_quality_score: 70 + + default_rules: + - spelling + - grammar + - formatting + - structure + - links + - images + + max_errors: 50 + max_warnings: 100 + +# Storage settings +storage: + type: "filesystem" # or "s3", "gcs", "azure" + base_path: "./published-docs" + versioning: true + retention_days: 365 + +# Cache settings +cache: + enabled: true + ttl: 3600 + max_size: 1GB + +# Rate limiting +rate_limit: + enabled: true + requests_per_minute: 100 + burst: 20 + +# Logging +logging: + level: "info" # debug, info, warn, error + format: "json" + output: "stdout" + +# Authentication +authentication: + type: "bearer" # bearer, api_key, oauth2 + token_expiry: 3600 + +# Webhook settings +webhooks: + enabled: true + retry_attempts: 3 + retry_delay: 5s + timeout: 10s + +# Transformation settings +transformation: + pandoc: + enabled: true + version: "latest" + + markdown: + flavor: "gfm" # GitHub Flavored Markdown + extensions: + - tables + - strikethrough + - task_lists + - autolinks + + html: + sanitize: true + allow_unsafe: false + +# Template settings +templates: + enabled: true + directory: "./templates" + cache_templates: true + +# Metadata defaults +metadata: + required_fields: + - title + - author + + optional_fields: + - description + - tags + - version + - category + - last_updated + +# Categories +categories: + - guides + - tutorials + - reference + - api + - concepts + - troubleshooting + - best-practices + - release-notes + +# Quality checks +quality: + min_words: 100 + max_words: 10000 + readability_score: 60 + check_broken_links: true + check_images: true + check_code_blocks: true + +# Notification settings +notifications: + enabled: true + channels: + - email + - webhook + + events: + - document_published + - document_updated + - document_deleted + - validation_failed + - transform_failed diff --git a/docs-publishing-service/examples/README.md b/docs-publishing-service/examples/README.md new file mode 100644 index 0000000..b026804 --- /dev/null +++ b/docs-publishing-service/examples/README.md @@ -0,0 +1,300 @@ +# Examples + +Practical examples for using the Documentation Publishing Service. + +## Directory Structure + +``` +examples/ +├── api/ # API usage examples +├── cli/ # Command-line examples +├── sdk/ # SDK examples for different languages +├── workflows/ # Workflow configuration examples +└── sample-docs/ # Sample documentation +``` + +## Quick Examples + +### Publishing a Document via API + +```bash +# Using cURL +curl -X POST https://api.docs-publishing.example.com/v1/publish \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "content": "# My Document\n\nThis is my documentation.", + "format": "markdown", + "brand": "example-brand", + "category": "guides", + "metadata": { + "title": "My First Document", + "author": "John Doe", + "version": "1.0.0" + } + }' +``` + +### Publishing from a File + +```bash +# Publish a markdown file +curl -X POST https://api.docs-publishing.example.com/v1/publish \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d @- < { + const response = await axios.post( + 'https://api.docs-publishing.example.com/v1/publish', + { + content: '# My Document\n\nContent here', + format: 'markdown', + brand: 'example-brand', + category: 'guides', + metadata: { + title: 'My Document', + author: 'Jane Doe' + } + }, + { + headers: { + 'Authorization': `Bearer ${process.env.DOCS_API_KEY}`, + 'Content-Type': 'application/json' + } + } + ); + + console.log('Published:', response.data); +}; + +publishDoc(); +``` + +### Python + +```python +import requests +import os + +def publish_document(content, metadata): + response = requests.post( + 'https://api.docs-publishing.example.com/v1/publish', + json={ + 'content': content, + 'format': 'markdown', + 'brand': 'example-brand', + 'category': 'guides', + 'metadata': metadata + }, + headers={ + 'Authorization': f'Bearer {os.environ["DOCS_API_KEY"]}', + 'Content-Type': 'application/json' + } + ) + + return response.json() + +# Usage +doc_content = """ +# Getting Started + +This is a sample document. +""" + +metadata = { + 'title': 'Getting Started', + 'author': 'Documentation Team', + 'version': '1.0.0' +} + +result = publish_document(doc_content, metadata) +print(f"Published: {result['id']}") +``` + +### Go + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "net/http" + "os" +) + +type PublishRequest struct { + Content string `json:"content"` + Format string `json:"format"` + Brand string `json:"brand"` + Category string `json:"category"` + Metadata map[string]string `json:"metadata"` +} + +func publishDocument(content string, metadata map[string]string) error { + req := PublishRequest{ + Content: content, + Format: "markdown", + Brand: "example-brand", + Category: "guides", + Metadata: metadata, + } + + jsonData, _ := json.Marshal(req) + + httpReq, _ := http.NewRequest( + "POST", + "https://api.docs-publishing.example.com/v1/publish", + bytes.NewBuffer(jsonData), + ) + + httpReq.Header.Set("Authorization", "Bearer "+os.Getenv("DOCS_API_KEY")) + httpReq.Header.Set("Content-Type", "application/json") + + client := &http.Client{} + resp, err := client.Do(httpReq) + if err != nil { + return err + } + defer resp.Body.Close() + + fmt.Println("Published successfully") + return nil +} + +func main() { + content := "# Getting Started\n\nSample documentation" + metadata := map[string]string{ + "title": "Getting Started", + "author": "Dev Team", + } + + publishDocument(content, metadata) +} +``` + +## Batch Processing + +### Publishing Multiple Documents + +```bash +#!/bin/bash + +# Publish all markdown files in a directory +for file in docs/*.md; do + echo "Publishing $file" + + # Extract title from first heading + TITLE=$(grep -m 1 "^# " "$file" | sed 's/# //') + + curl -X POST https://api.docs-publishing.example.com/v1/publish \ + -H "Authorization: Bearer $DOCS_API_KEY" \ + -H "Content-Type: application/json" \ + -d @- < **Tip:** Share helpful tips and recommendations. + +## Next Steps + +Now that you've completed this guide, you can: + +1. Next recommended action 1 +2. Next recommended action 2 +3. Next recommended action 3 + +## Related Resources + +- [Related Document 1](link) +- [Related Document 2](link) +- [External Resource](link) + +## Feedback + +Have questions or suggestions? [Contact us](mailto:docs@example.com) or [open an issue](link-to-issues). + +--- + +**Last Updated:** YYYY-MM-DD +**Version:** 1.0.0 diff --git a/docs-publishing-service/templates/tutorial.md b/docs-publishing-service/templates/tutorial.md new file mode 100644 index 0000000..7bc8b3e --- /dev/null +++ b/docs-publishing-service/templates/tutorial.md @@ -0,0 +1,229 @@ +--- +title: "Tutorial: [Task Name]" +author: "Author Name" +category: "tutorials" +version: "1.0.0" +date: "YYYY-MM-DD" +tags: + - tutorial + - hands-on +difficulty: "beginner" # beginner, intermediate, advanced +duration: "30 minutes" +description: "Learn how to [accomplish something] in this step-by-step tutorial" +status: "draft" +--- + +# Tutorial: [Task Name] + +## Introduction + +In this tutorial, you'll learn how to [accomplish the main goal]. By the end, you'll be able to: + +- Learning objective 1 +- Learning objective 2 +- Learning objective 3 + +**Estimated time:** 30 minutes +**Difficulty level:** Beginner + +## What You'll Build + +Describe the end result of the tutorial. Include a screenshot or diagram if possible. + +``` +[Screenshot or diagram placeholder] +``` + +## Prerequisites + +Before you start, make sure you have: + +- [ ] Prerequisite 1 (with setup link if needed) +- [ ] Prerequisite 2 +- [ ] Prerequisite 3 + +**Required skills:** +- Skill 1 (basic/intermediate/advanced) +- Skill 2 + +## Step 1: [First Major Step] + +Brief description of what you'll accomplish in this step. + +1. First action in this step + + ```language + // Code for first action + code here + ``` + +2. Second action in this step + + ```language + // Code for second action + code here + ``` + +3. Third action + + **Expected result:** + ``` + Output you should see + ``` + +> **Note:** Provide helpful context or explain what's happening. + +### Verify Step 1 + +Check that everything is working: + +```language +// Verification command +verification code +``` + +You should see: +``` +Expected verification output +``` + +✓ **Checkpoint:** At this point, you should have [what's completed]. + +## Step 2: [Second Major Step] + +Continue with the next major step. + +1. First action + + ```language + // Code + code here + ``` + +2. Second action + + ```language + // Code + code here + ``` + +> **Tip:** Share helpful advice specific to this step. + +### Verify Step 2 + +```language +// Verification +verification code +``` + +✓ **Checkpoint:** You've now completed [what's completed]. + +## Step 3: [Third Major Step] + +Continue with additional steps as needed. + +1. Action description + + ```language + // Code + code here + ``` + +2. Action description + + ```language + // Code + code here + ``` + +### Verify Step 3 + +```language +// Verification +verification code +``` + +## Step 4: [Final Step] + +Complete the tutorial with final configurations or deployments. + +1. Final action + + ```language + // Code + code here + ``` + +### Final Verification + +Test the complete implementation: + +```language +// Full test command +test code +``` + +**Expected output:** +``` +Successful completion output +``` + +🎉 **Congratulations!** You've successfully completed the tutorial. + +## What You've Learned + +In this tutorial, you: + +- ✓ Learned concept/skill 1 +- ✓ Learned concept/skill 2 +- ✓ Learned concept/skill 3 + +## Troubleshooting + +### Problem 1 + +**Symptom:** What you see when there's a problem + +**Solution:** How to fix it + +```language +// Solution code if applicable +``` + +### Problem 2 + +**Symptom:** Another common issue + +**Solution:** How to resolve it + +## Next Steps + +Now that you've completed this tutorial, you can: + +1. **Try this next:** [Related Tutorial](link) +2. **Learn more about:** [Concept Doc](link) +3. **Explore:** [Advanced Features](link) + +## Clean Up + +If you want to remove what you created in this tutorial: + +```language +// Cleanup commands +cleanup code +``` + +## Additional Resources + +- [Official Documentation](link) +- [API Reference](link) +- [Community Examples](link) + +## Feedback + +Found an issue or have suggestions? [Let us know](mailto:docs@example.com) + +--- + +**Tutorial completed:** [DATE] +**Version:** 1.0.0 diff --git a/docs-publishing-service/workflows/README.md b/docs-publishing-service/workflows/README.md new file mode 100644 index 0000000..f1d7a48 --- /dev/null +++ b/docs-publishing-service/workflows/README.md @@ -0,0 +1,286 @@ +# GitHub Actions Workflows + +Automated workflows for documentation publishing and management. + +## Available Workflows + +### 1. Publish Documentation (`publish-docs.yml`) + +Automatically validates and publishes documentation when changes are pushed. + +**Triggers:** +- Push to `main` branch affecting documentation +- Pull requests affecting documentation +- Manual workflow dispatch + +**Features:** +- Validates documentation structure and content +- Checks spelling and grammar +- Publishes to brand-endorsed knowledge base +- Sends notifications on completion + +**Usage:** + +Place this workflow in your repository's `.github/workflows/` directory: + +```bash +cp docs-publishing-service/workflows/publish-docs.yml .github/workflows/ +``` + +**Required Secrets:** +- `DOCS_API_KEY` - API key for documentation publishing service +- `DOCS_API_URL` - (Optional) API endpoint URL + +**Manual Trigger:** + +You can manually trigger the workflow from GitHub Actions: +1. Go to Actions tab +2. Select "Publish Documentation" workflow +3. Click "Run workflow" +4. Choose brand and options + +### 2. Validate Documentation (`validate-docs.yml`) + +Runs comprehensive validation on documentation files. + +**Usage:** + +```yaml +name: Validate Docs +on: [pull_request] + +jobs: + validate: + uses: ./.github/workflows/validate-docs.yml +``` + +### 3. Generate Documentation Site (`generate-site.yml`) + +Builds a static documentation site from markdown files. + +**Usage:** + +```yaml +name: Generate Docs Site +on: + push: + branches: [main] + +jobs: + build: + uses: ./.github/workflows/generate-site.yml +``` + +## Configuration + +### Basic Setup + +1. **Copy workflow files:** + ```bash + mkdir -p .github/workflows + cp docs-publishing-service/workflows/*.yml .github/workflows/ + ``` + +2. **Add secrets:** + - Go to repository Settings > Secrets + - Add `DOCS_API_KEY` + - Optionally add `DOCS_API_URL` + +3. **Configure brand:** + - Set brand in workflow file or + - Use workflow dispatch to specify per run + +### Advanced Configuration + +#### Custom Validation Rules + +Add a `.docsconfig.yml` file to your repository: + +```yaml +validation: + min_words: 150 + max_words: 5000 + strict_mode: true + +brand: your-brand-name + +categories: + - guides + - tutorials + - reference +``` + +#### Custom Publishing Destination + +Configure publishing destinations in the workflow: + +```yaml +env: + DOCS_API_URL: https://your-api.example.com/v1 + BRAND: your-brand +``` + +#### Conditional Publishing + +Publish only from specific branches: + +```yaml +on: + push: + branches: + - main + - release/** + paths: + - 'docs/**' +``` + +## Workflow Examples + +### Example 1: Validate on PR, Publish on Merge + +```yaml +name: Documentation Pipeline + +on: + pull_request: + paths: + - 'docs/**' + push: + branches: + - main + paths: + - 'docs/**' + +jobs: + validate: + if: github.event_name == 'pull_request' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: ./docs-publishing-service/workflows/validate + + publish: + if: github.event_name == 'push' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: ./docs-publishing-service/workflows/publish +``` + +### Example 2: Multi-Brand Publishing + +```yaml +name: Publish to Multiple Brands + +on: + push: + branches: [main] + +jobs: + publish-brand-a: + uses: ./docs-publishing-service/workflows/publish-docs.yml + with: + brand: brand-a + secrets: + api_key: ${{ secrets.BRAND_A_API_KEY }} + + publish-brand-b: + uses: ./docs-publishing-service/workflows/publish-docs.yml + with: + brand: brand-b + secrets: + api_key: ${{ secrets.BRAND_B_API_KEY }} +``` + +### Example 3: Scheduled Documentation Updates + +```yaml +name: Update Documentation + +on: + schedule: + - cron: '0 0 * * 0' # Weekly on Sunday + workflow_dispatch: + +jobs: + update: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Update documentation metadata + run: | + # Update timestamps, versions, etc. + find docs -name "*.md" -exec sed -i "s/last_updated:.*/last_updated: $(date -I)/" {} \; + - name: Commit changes + run: | + git config user.name "GitHub Actions" + git config user.email "actions@github.com" + git commit -am "Update documentation metadata" || exit 0 + git push +``` + +## Integration with CI/CD + +### Jenkins + +```groovy +pipeline { + agent any + stages { + stage('Validate Docs') { + steps { + sh 'curl -X POST -H "Authorization: Bearer $DOCS_API_KEY" $DOCS_API_URL/validate' + } + } + stage('Publish Docs') { + when { branch 'main' } + steps { + sh 'curl -X POST -H "Authorization: Bearer $DOCS_API_KEY" $DOCS_API_URL/publish' + } + } + } +} +``` + +### GitLab CI + +```yaml +validate-docs: + stage: test + script: + - curl -X POST -H "Authorization: Bearer $DOCS_API_KEY" $DOCS_API_URL/validate + +publish-docs: + stage: deploy + only: + - main + script: + - curl -X POST -H "Authorization: Bearer $DOCS_API_KEY" $DOCS_API_URL/publish +``` + +## Troubleshooting + +### Workflow Not Triggering + +- Check file paths in `paths:` filter +- Ensure branch names match +- Verify permissions in repository settings + +### API Authentication Failures + +- Verify `DOCS_API_KEY` secret is set +- Check API key hasn't expired +- Ensure API key has proper permissions + +### Validation Failures + +- Review validation rules in brand config +- Check documentation format +- Ensure all required fields are present + +## Support + +For workflow issues: +1. Check workflow logs in GitHub Actions +2. Review [main documentation](../README.md) +3. Open an issue in the repository diff --git a/docs-publishing-service/workflows/publish-docs.yml b/docs-publishing-service/workflows/publish-docs.yml new file mode 100644 index 0000000..e2c5233 --- /dev/null +++ b/docs-publishing-service/workflows/publish-docs.yml @@ -0,0 +1,225 @@ +name: Publish Documentation + +on: + push: + branches: + - main + - docs/** + paths: + - 'docs/**' + - '**.md' + pull_request: + paths: + - 'docs/**' + - '**.md' + workflow_dispatch: + inputs: + brand: + description: 'Brand to publish to' + required: true + type: string + dry_run: + description: 'Validate only without publishing' + required: false + type: boolean + default: false + +env: + DOCS_API_URL: ${{ secrets.DOCS_API_URL || 'https://api.docs-publishing.example.com/v1' }} + +jobs: + validate: + name: Validate Documentation + runs-on: ubuntu-latest + outputs: + docs-changed: ${{ steps.changes.outputs.docs }} + + steps: + - name: Checkout code + uses: actions/checkout@v3 + with: + fetch-depth: 2 + + - name: Check for documentation changes + id: changes + run: | + if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then + echo "docs=true" >> $GITHUB_OUTPUT + else + git diff --name-only HEAD~1 HEAD | grep -q -E '\.(md|markdown|rst)$' && echo "docs=true" >> $GITHUB_OUTPUT || echo "docs=false" >> $GITHUB_OUTPUT + fi + + - name: Get changed files + if: steps.changes.outputs.docs == 'true' + id: changed-files + run: | + if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then + FILES=$(find docs -type f \( -name "*.md" -o -name "*.markdown" -o -name "*.rst" \)) + else + FILES=$(git diff --name-only HEAD~1 HEAD | grep -E '\.(md|markdown|rst)$') + fi + echo "files<> $GITHUB_OUTPUT + echo "$FILES" >> $GITHUB_OUTPUT + echo "EOF" >> $GITHUB_OUTPUT + + - name: Validate documentation + if: steps.changes.outputs.docs == 'true' + run: | + echo "Validating documentation files..." + + # Install validation tools + pip install markdown-lint pyyaml + + # Validate each file + while IFS= read -r file; do + if [ -f "$file" ]; then + echo "Validating $file" + + # Check frontmatter + if head -1 "$file" | grep -q "^---$"; then + echo "✓ Frontmatter found" + else + echo "⚠ Warning: No frontmatter in $file" + fi + + # Check minimum content length + WORD_COUNT=$(wc -w < "$file") + if [ "$WORD_COUNT" -lt 100 ]; then + echo "⚠ Warning: $file has less than 100 words ($WORD_COUNT words)" + else + echo "✓ Content length OK ($WORD_COUNT words)" + fi + fi + done <<< "${{ steps.changed-files.outputs.files }}" + + - name: Spell check + if: steps.changes.outputs.docs == 'true' + continue-on-error: true + run: | + # Install spell checker + sudo apt-get update && sudo apt-get install -y aspell + + echo "Running spell check..." + while IFS= read -r file; do + if [ -f "$file" ]; then + aspell list < "$file" | sort -u > /tmp/misspelled-$RANDOM.txt || true + fi + done <<< "${{ steps.changed-files.outputs.files }}" + + publish: + name: Publish to Knowledge Base + runs-on: ubuntu-latest + needs: validate + if: | + needs.validate.outputs.docs-changed == 'true' && + (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && + github.ref == 'refs/heads/main' + + steps: + - name: Checkout code + uses: actions/checkout@v3 + + - name: Set up environment + run: | + echo "Setting up publishing environment..." + pip install requests pyyaml + + - name: Determine brand + id: brand + run: | + if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then + BRAND="${{ github.event.inputs.brand }}" + else + # Try to detect brand from repository or use default + BRAND="${GITHUB_REPOSITORY_OWNER}" + fi + echo "brand=${BRAND}" >> $GITHUB_OUTPUT + echo "Publishing to brand: ${BRAND}" + + - name: Publish documentation + if: github.event.inputs.dry_run != 'true' + env: + DOCS_API_KEY: ${{ secrets.DOCS_API_KEY }} + BRAND: ${{ steps.brand.outputs.brand }} + run: | + echo "Publishing documentation to $BRAND..." + + # Find all documentation files + find docs -type f \( -name "*.md" -o -name "*.markdown" \) | while read -r file; do + echo "Publishing $file" + + # Extract metadata from frontmatter + TITLE=$(grep '^title:' "$file" | head -1 | sed 's/title: *"\(.*\)"/\1/' || basename "$file" .md) + CATEGORY=$(grep '^category:' "$file" | head -1 | sed 's/category: *"\(.*\)"/\1/' || echo "general") + + # Create JSON payload + PAYLOAD=$(cat <> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "✓ Validation completed successfully" >> $GITHUB_STEP_SUMMARY + echo "✓ No errors found" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "**Note:** This was a dry run. Documentation was not published." >> $GITHUB_STEP_SUMMARY + + - name: Create deployment summary + if: github.event.inputs.dry_run != 'true' + run: | + echo "## Documentation Published" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "✓ Documentation published to **${{ steps.brand.outputs.brand }}**" >> $GITHUB_STEP_SUMMARY + echo "✓ Commit: ${{ github.sha }}" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "### Published Files" >> $GITHUB_STEP_SUMMARY + find docs -type f \( -name "*.md" -o -name "*.markdown" \) | while read -r file; do + echo "- $file" >> $GITHUB_STEP_SUMMARY + done + + notify: + name: Send Notifications + runs-on: ubuntu-latest + needs: [validate, publish] + if: always() && needs.publish.result != 'skipped' + + steps: + - name: Notify on success + if: needs.publish.result == 'success' + run: | + echo "Documentation published successfully" + # Add notification logic (Slack, email, etc.) + + - name: Notify on failure + if: needs.publish.result == 'failure' + run: | + echo "Documentation publishing failed" + # Add failure notification logic From 690a9d59c7a9f7d596b3e4553977557599a393c1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 16 Oct 2025 00:42:59 +0000 Subject: [PATCH 3/5] Add comprehensive templates, validation rules, and examples Co-authored-by: Shivansh9000 <15914113+Shivansh9000@users.noreply.github.com> --- docs-publishing-service/CONTRIBUTING.md | 409 ++++++++++++++++++ .../config/validation-rules.yaml | 241 +++++++++++ .../examples/sample-docs/getting-started.md | 373 ++++++++++++++++ .../templates/api-reference.md | 408 +++++++++++++++++ .../templates/quickstart.md | 252 +++++++++++ .../templates/release-notes.md | 304 +++++++++++++ .../templates/troubleshooting.md | 387 +++++++++++++++++ 7 files changed, 2374 insertions(+) create mode 100644 docs-publishing-service/CONTRIBUTING.md create mode 100644 docs-publishing-service/config/validation-rules.yaml create mode 100644 docs-publishing-service/examples/sample-docs/getting-started.md create mode 100644 docs-publishing-service/templates/api-reference.md create mode 100644 docs-publishing-service/templates/quickstart.md create mode 100644 docs-publishing-service/templates/release-notes.md create mode 100644 docs-publishing-service/templates/troubleshooting.md diff --git a/docs-publishing-service/CONTRIBUTING.md b/docs-publishing-service/CONTRIBUTING.md new file mode 100644 index 0000000..1d7d9c7 --- /dev/null +++ b/docs-publishing-service/CONTRIBUTING.md @@ -0,0 +1,409 @@ +# Contributing to Documentation Publishing Service + +Thank you for your interest in contributing to the Documentation Publishing Service! This guide will help you get started. + +## How to Contribute + +There are many ways to contribute: + +- 📝 Improve documentation +- 🐛 Report bugs +- ✨ Suggest new features +- 🔧 Submit code improvements +- 📋 Add new templates +- 🎨 Enhance brand configurations +- ✅ Add validation rules + +## Getting Started + +### 1. Fork the Repository + +Fork the repository and clone it locally: + +```bash +git clone https://github.com/YOUR-USERNAME/.github-private.git +cd .github-private +``` + +### 2. Create a Branch + +Create a branch for your contribution: + +```bash +git checkout -b feature/your-feature-name +# or +git checkout -b fix/bug-description +# or +git checkout -b docs/documentation-improvement +``` + +Branch naming conventions: +- `feature/` - New features +- `fix/` - Bug fixes +- `docs/` - Documentation updates +- `config/` - Configuration changes +- `template/` - New templates + +## Making Changes + +### Documentation Improvements + +When improving documentation: + +1. **Use existing templates** from `docs-publishing-service/templates/` +2. **Include frontmatter** with proper metadata +3. **Follow style guidelines** in brand configurations +4. **Add examples** where applicable +5. **Test your changes** by validating the documentation + +Example: + +```bash +# Validate your documentation +curl -X POST https://api.docs-publishing.example.com/v1/validate \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -d @your-doc.md +``` + +### Adding New Templates + +To add a new documentation template: + +1. Create the template in `docs-publishing-service/templates/` +2. Follow the existing template structure +3. Include comprehensive frontmatter +4. Add placeholders for customization +5. Document the template in `templates/README.md` + +Template structure: +```markdown +--- +title: "Template Title" +category: "template-category" +# ... other metadata +--- + +# Template Content + +Use {{placeholders}} for variable content +``` + +### Adding Brand Configurations + +To add a new brand configuration: + +1. Create directory: `docs-publishing-service/config/brands/your-brand/` +2. Add required files: + - `config.yaml` - Brand settings + - `styles.css` - Brand styling + - `validation.yaml` - Validation rules +3. Follow the example brand structure +4. Test with sample documentation + +### Adding Validation Rules + +When adding new validation rules: + +1. Add to `config/validation-rules.yaml` for global rules +2. Or add to brand-specific `validation.yaml` +3. Document the rule with: + - Rule name and description + - When it applies + - Example violations + - How to fix + +### Code Contributions + +If contributing code (API implementation, validators, etc.): + +1. Follow the existing code style +2. Add tests for new functionality +3. Update documentation +4. Ensure all tests pass + +## Validation and Testing + +Before submitting your contribution: + +### 1. Validate Documentation + +```bash +# Check your documentation meets standards +validate-docs your-file.md +``` + +### 2. Test Configurations + +```bash +# Test brand configuration +test-config config/brands/your-brand/ +``` + +### 3. Lint Files + +```bash +# Lint YAML files +yamllint config/**/*.yaml + +# Lint Markdown files +markdownlint **/*.md +``` + +## Commit Guidelines + +### Commit Message Format + +Use clear, descriptive commit messages: + +``` +(): + + + +