HG Content System - Comprehensive Documentation Implementation Plan¶

Executive Summary¶

Implementation plan for creating a unified documentation portal using MkDocs Material for the HG Content Generation System monorepo. This will consolidate API docs, user guides, and developer documentation into a single, versioned, searchable site.

Current State Analysis¶

Existing Documentation Assets¶

Markdown Docs: 17 comprehensive docs in /docs/ covering architecture, deployment, APIs
OpenAPI Spec: /openapi/hgcontent-api-v1.yaml exists
Python Services: CPM, IM, SMM, External API with docstrings
TypeScript Frontend: Next.js app with JSDoc comments
Test Documentation: Complete test specifications in /docs/tests/

Gaps to Address¶

No unified documentation site
API documentation not auto-generated from code
No versioning system for docs
TypeScript API docs not generated
Python docstrings not exposed as API docs
OpenAPI spec not integrated into browseable docs

Proposed Architecture: MkDocs Material Portal¶

Technology Stack¶

MkDocs Material: Main documentation framework
mkdocs-monorepo-plugin: Merge multiple docs folders
mkdocstrings: Python API documentation from docstrings
TypeDoc + typedoc-plugin-markdown: TypeScript API docs
mkdocs-swagger-ui-tag: Interactive OpenAPI documentation
mike: Documentation versioning
GitHub Pages: Hosting platform

Repository Structure¶

hg-content/
├── docs/                          # Root documentation
│   ├── index.md                   # Landing page
│   ├── getting-started.md         # Quick start guide
│   ├── architecture/              # System architecture docs
│   ├── deployment/                # Deployment guides
│   └── api/                       # API landing pages
│       ├── index.md               # API overview
│       ├── http-api.md            # OpenAPI embed page
│       ├── typescript-sdk.md     # Link to generated TS docs
│       └── python-sdk.md          # Link to Python API docs
├── apps/
│   ├── frontend/
│   │   ├── docs/                  # Frontend-specific docs
│   │   │   ├── components.md      # Component library
│   │   │   └── api/               # Generated TypeDoc output
│   │   ├── typedoc.json           # TypeDoc config
│   │   └── mkdocs.yml             # Frontend sub-config
│   ├── cpm/
│   │   ├── docs/                  # CPM service docs
│   │   │   ├── index.md           # Service overview
│   │   │   └── api.md             # mkdocstrings API
│   │   └── mkdocs.yml             # CPM sub-config
│   ├── im/
│   │   ├── docs/                  # IM service docs
│   │   └── mkdocs.yml
│   ├── smm/
│   │   ├── docs/                  # SMM service docs
│   │   └── mkdocs.yml
│   └── external/
│       ├── docs/                  # External API docs
│       └── mkdocs.yml
├── openapi/
│   ├── public-v1.yaml             # Public API spec
│   ├── internal.yaml              # Internal services spec
│   └── schemas/                   # Shared schemas
├── mkdocs.yml                     # Root MkDocs config
├── requirements-docs.txt          # Documentation dependencies
└── .github/
    └── workflows/
        └── docs.yml               # CI/CD for docs

Implementation Plan¶

Phase 1: Foundation Setup (Week 1)¶

1.1 Install MkDocs Material and Core Plugins¶

# requirements-docs.txt
mkdocs==1.5.3
mkdocs-material==9.5.3
mkdocs-monorepo-plugin==1.0.5
mkdocstrings[python]==0.24.0
mkdocs-swagger-ui-tag==0.6.8
mike==2.0.0

1.2 Create Root MkDocs Configuration¶

# mkdocs.yml
site_name: HG Content Generation System
site_description: AI-powered content generation platform
site_url: https://cvsloane.github.io/hg-content
repo_url: https://github.com/cvsloane/hg-content
repo_name: cvsloane/hg-content

theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.indexes
    - navigation.top
    - search.suggest
    - search.highlight
    - content.code.copy
    - content.code.annotate
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

plugins:
  - search
  - monorepo
  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          options:
            show_source: true
            show_root_heading: true
  - swagger-ui-tag:
      supportedSubmitMethods: ["get", "post", "put", "delete"]
      validatorUrl: null

extra:
  version:
    provider: mike
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/cvsloane/hg-content

nav:
  - Home: index.md
  - Getting Started:
      - Quick Start: getting-started.md
      - Installation: installation.md
      - Configuration: configuration.md
  - Architecture:
      - Overview: architecture/index.md
      - System Design: architecture/system-design.md
      - Database Schema: architecture/database-schema.md
      - Data Flow: architecture/data-flow.md
  - User Guide:
      - Dashboard: user-guide/dashboard.md
      - Content Generation: user-guide/content-generation.md
      - Client Management: user-guide/clients.md
      - Templates: user-guide/templates.md
  - API Reference:
      - Overview: api/index.md
      - REST API: api/http-api.md
      - Python SDK:
          - CPM Client: !include apps/cpm/mkdocs.yml:nav
          - IM Client: !include apps/im/mkdocs.yml:nav
          - External API: !include apps/external/mkdocs.yml:nav
      - TypeScript SDK: !include apps/frontend/mkdocs.yml:nav
  - Deployment:
      - Overview: deployment/index.md
      - Vercel: deployment/vercel.md
      - Railway: deployment/railway.md
      - Supabase: deployment/supabase.md
      - Ollama: deployment/ollama.md
  - Development:
      - Setup: development/setup.md
      - Testing: development/testing.md
      - Contributing: development/contributing.md

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - admonition
  - pymdownx.details
  - toc:
      permalink: true

Phase 2: Python API Documentation (Week 1)¶

2.1 Configure mkdocstrings for Each Service¶

CPM Service (apps/cpm/mkdocs.yml):

nav:
  - CPM Overview: index.md
  - API Reference:
      - LLM Clients: api/llm_client.md
      - Content Processor: api/content_processor.md
      - Database Operations: api/database.md
      - Models: api/models.md

CPM API Page (apps/cpm/docs/api/llm_client.md):

# LLM Client API

## BaseLLMClient

::: apps.cpm.llm_client.BaseLLMClient
    options:
      show_source: true
      members_order: source

## OpenAIClient

::: apps.cpm.llm_client.OpenAIClient
    options:
      show_source: false
      inherited_members: true

## OllamaClient

::: apps.cpm.llm_client.OllamaClient
    options:
      show_source: false
      inherited_members: true

2.2 Add Docstrings to Python Code¶

Enhance existing Python files with comprehensive docstrings:

# apps/cpm/llm_client.py
class BaseLLMClient(ABC):
    """Abstract base class for LLM client implementations.

    This class defines the interface that all LLM clients must implement
    to ensure compatibility with the content generation system.

    Attributes:
        provider (str): The name of the LLM provider.
        model (str): The specific model being used.

    Example:
        ```python
        client = OpenAIClient(api_key="your-key")
        response = await client.generate(
            prompt="Write a blog post about AI",
            content_type="blog",
            max_tokens=1000
        )
        print(response.content)
        ```
    """

Phase 3: TypeScript API Documentation (Week 2)¶

3.1 Configure TypeDoc¶

Create apps/frontend/typedoc.json:

{
  "entryPoints": ["src/index.ts"],
  "out": "docs/api",
  "plugin": ["typedoc-plugin-markdown"],
  "excludePrivate": true,
  "excludeProtected": true,
  "readme": "none",
  "githubPages": false,
  "hideBreadcrumbs": true,
  "hideInPageTOC": true
}

3.2 Add TypeDoc Scripts¶

Update apps/frontend/package.json:

{
  "scripts": {
    "docs:generate": "typedoc",
    "docs:clean": "rm -rf docs/api"
  },
  "devDependencies": {
    "typedoc": "^0.25.7",
    "typedoc-plugin-markdown": "^3.17.1"
  }
}

3.3 Frontend Sub-config¶

Create apps/frontend/mkdocs.yml:

nav:
  - Frontend Overview: index.md
  - Components:
      - Overview: components/index.md
      - Forms: components/forms.md
      - Dashboard: components/dashboard.md
  - API Reference:
      - Hooks: api/modules/hooks.md
      - Stores: api/modules/stores.md
      - Utils: api/modules/utils.md
      - Types: api/interfaces/types.md

Phase 4: OpenAPI Integration (Week 2)¶

4.1 Consolidate OpenAPI Specs¶

Merge service specs into comprehensive files:

# openapi/public-v1.yaml
openapi: 3.0.0
info:
  title: HG Content Generation API
  version: 1.0.0
  description: Public API for content generation
servers:
  - url: https://api.hgcontent.com/v1
    description: Production
  - url: http://localhost:8002/api/v1
    description: Local development
paths:
  /content/generate:
    $ref: './paths/content-generate.yaml'
  /jobs/{jobId}/status:
    $ref: './paths/job-status.yaml'
components:
  schemas:
    $ref: './schemas/index.yaml'
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key

4.2 Create OpenAPI Documentation Page¶

docs/api/http-api.md:

# REST API Reference

## Authentication
All API requests require an API key passed in the `X-API-Key` header.

## Interactive Documentation
Explore and test the API using the interactive documentation below:

<swagger-ui src="/openapi/public-v1.yaml"/>

## Base URLs
- Production: `https://api.hgcontent.com/v1`
- Development: `http://localhost:8002/api/v1`

## Rate Limiting
- 100 requests per minute per API key
- 1000 requests per hour per API key

Phase 5: CI/CD Integration (Week 3)¶

5.1 GitHub Actions Workflow¶

Create .github/workflows/docs.yml:

on

id=__codelineno-11-1 name=__codelineno-11-1 href=#__codelineno-11-1>name: Deploy Documentation class=p>: push: branches: [main] paths: - 'docs/**' - 'apps/**/docs/**' - 'mkdocs.yml' - 'apps/**/mkdocs.yml' - '**.py' # Rebuild on Python changes - '**.ts' # Rebuild on TypeScript changes workflow_dispatch: class=nt>jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 # Full history for mike - name: Setup Python uses: actions/setup-python@v4 with: python-version: '3.11' - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '18' - name: Cache dependencies uses: actions/cache@v3 with: path: | ~/.cache/pip ~/.npm key: ${{ runner.os }}-docs-${{ hashFiles('**/requirements-docs.txt', '**/package-lock.json') }} - name: Install Python dependencies run: | pip install -r requirements-docs.txt pip install -e apps/cpm pip install -e apps/im pip install -e apps/external - name: Generate TypeScript docs run: | cd apps/frontend npm ci npm run docs:generate - name: Configure Git run: | git config user.name github-actions git config user.email github-actions@github.com - name: Deploy docs run: | mike deploy --push --update-aliases ${{ github.ref_name }} latest

5.2 Versioning Strategy¶

Use mike for version management:

# Deploy version 1.0
mike deploy 1.0 latest --push

# Deploy development version
mike deploy dev --push

# List versions
mike list

# Set default version
mike set-default latest --push

Phase 6: Search and Enhancement (Week 3)¶

6.1 Apply for Algolia DocSearch¶

Submit application at https://docsearch.algolia.com/
Add configuration once approved:

# mkdocs.yml
extra:
  algolia:
    appId: YOUR_APP_ID
    apiKey: YOUR_SEARCH_API_KEY
    indexName: hg-content

6.2 Add Code Examples¶

Create docs/examples/ directory with practical examples:

# docs/examples/python-sdk.md
# Python SDK Examples

## Basic Content Generation
\```python
from hgcontent import CPMClient

client = CPMClient(api_key="your-key")

# Generate blog content
response = client.generate(
    topic="AI in Healthcare",
    content_type="blog",
    keywords=["AI", "healthcare", "innovation"],
    tone="professional"
)

print(response.content)
\```

Phase 7: Testing and Validation (Week 4)¶

7.1 Documentation Tests¶

Add doc build tests to CI:

# .github/workflows/test-docs.yml
name: Test Documentation Build

on:
  pull_request:
    paths:
      - 'docs/**'
      - 'mkdocs.yml'

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Python
        uses: actions/setup-python@v4
      - name: Install dependencies
        run: pip install -r requirements-docs.txt
      - name: Build docs
        run: mkdocs build --strict
      - name: Check for broken links
        run: |
          pip install linkchecker
          linkchecker site/

7.2 Local Development¶

Add convenience scripts:

// package.json
{
  "scripts": {
    "docs:serve": "mkdocs serve",
    "docs:build": "mkdocs build",
    "docs:deploy": "mike deploy dev --push"
  }
}

Migration Strategy¶

Week 1: Foundation¶

Install MkDocs Material and dependencies
Create root configuration
Set up basic navigation structure
Migrate existing markdown docs

Week 2: API Documentation¶

Add mkdocstrings configuration
Enhance Python docstrings
Configure TypeDoc for TypeScript
Generate initial API docs

Week 3: Integration¶

Set up OpenAPI/Swagger UI
Configure CI/CD pipeline
Deploy to GitHub Pages
Set up versioning with mike

Week 4: Polish¶

Apply for Algolia DocSearch
Add code examples
Create tutorials
Test and validate all links

Success Metrics¶

Immediate (Week 4)¶

Single documentation site deployed
All existing docs migrated
API documentation auto-generated
OpenAPI spec browseable
CI/CD pipeline functional

Short-term (Month 2)¶

Long-term (Month 3)¶

Maintenance Plan¶

Daily¶

Monitor build status
Check for broken links
Review user feedback

Weekly¶

Update code examples
Add new guides based on support queries
Review and merge documentation PRs

Monthly¶

Review analytics
Update OpenAPI specs
Release new version if needed
Update dependencies

Quarterly¶

Major documentation review
User survey for improvements
Performance optimization
SEO review and updates

Commands Reference¶

# Local development
mkdocs serve                   # Start dev server on http://127.0.0.1:8000
mkdocs build                    # Build static site
mkdocs build --strict          # Build with warnings as errors

# TypeScript docs
cd apps/frontend && npm run docs:generate

# Python docs (automatic via mkdocstrings)
# Just ensure proper docstrings in code

# Deployment
mike deploy 1.0 latest --push  # Deploy version 1.0
mike list                       # List all versions
mike serve                      # Preview versioned site locally

# Testing
linkchecker site/               # Check for broken links
mkdocs build --strict          # Validate build

Resources¶

Documentation¶

Examples¶

Next Steps¶

Immediate Action: Install dependencies and create root mkdocs.yml
This Week: Migrate existing docs and set up basic structure
Next Week: Add API documentation generation
Following Week: Deploy to GitHub Pages with CI/CD
Month 2: Polish, search, and versioning

This plan provides a comprehensive roadmap for implementing professional-grade documentation for the HG Content Generation System using MkDocs Material as the unified portal.

See also: APP_AND_API_QUICK_GUIDE.md for immediate user and API instructions.