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/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: + +``` +(): + + + +