Documentation Guide

Documentation Guide

This directory contains the source files for the CCProxy API documentation, built with MkDocs and Material for MkDocs.

Quick Start

Prerequisites

• Python 3.11+
• uv (preferred) or pip

Setup and Serve Locally

# Install documentation dependencies
./Taskfile docs-install

# Serve documentation with live reload
./Taskfile docs-serve

The documentation will be available at http://127.0.0.1:8080.

Build for Production

# Build static documentation
./Taskfile docs-build

# Clean build artifacts
./Taskfile docs-clean

Documentation Structure

docs/
├── index.md                    # Home page
├── getting-started/            # Installation and setup
│   ├── quickstart.md          # Quick start guide
│   ├── installation.md        # Detailed installation
│   └── configuration.md       # Configuration reference
├── user-guide/                # User documentation
│   ├── api-usage.md           # API usage examples
│   ├── authentication.md     # Authentication guide
│   ├── streaming.md           # Streaming documentation
│   └── error-handling.md      # Error handling guide
├── api-reference/              # API documentation
│   ├── overview.md            # API overview
│   ├── anthropic.md           # Anthropic endpoints
│   ├── openai.md              # OpenAI endpoints
│   ├── models.md              # Available models
│   └── health.md              # Health endpoints
├── developer-guide/            # Developer documentation
│   ├── architecture.md        # System architecture
│   ├── development.md         # Development setup
│   ├── testing.md             # Testing guide (606 focused tests)
│   └── contributing.md        # Contribution guidelines
├── deployment/                 # Deployment guides
│   ├── docker.md              # Docker deployment
│   ├── production.md          # Production deployment
│   ├── kubernetes.md          # Kubernetes deployment
│   └── monitoring.md          # Monitoring setup
├── examples/                   # Code examples
│   ├── python-client.md       # Python examples
│   ├── curl.md                # curl examples
│   ├── javascript.md          # JavaScript examples
│   └── openai-sdk.md          # OpenAI SDK examples
├── reference/                  # Auto-generated API docs
│   └── (generated from source code)
└── assets/                     # Static assets
    ├── extra.css              # Custom CSS
    ├── extra.js               # Custom JavaScript
    └── images/                # Images and icons

Features

Core Features

• Material Design: Modern, responsive theme with dark/light mode
• Auto-generated API docs: Documentation generated from Python source code
• Search: Full-text search across all documentation
• Code highlighting: Syntax highlighting for multiple languages
• Copy buttons: One-click code copying
• Mobile responsive: Optimized for mobile and desktop

Advanced Features

• Live reload: Automatic page refresh during development
• Mermaid diagrams: Support for flowcharts and diagrams
• OpenAPI/Swagger: Interactive API documentation
• GitHub integration: Edit buttons linking to source files
• Version management: Support for multiple documentation versions

Plugins Enabled

• mkdocstrings: Auto-generated Python API documentation
• search: Enhanced search functionality
• section-index: Automatic section indices
• swagger-ui-tag: Interactive API documentation
• mermaid2: Diagram support
• glightbox: Image lightbox
• minify: CSS/JS minification for production

Configuration

The documentation is configured in mkdocs.yml in the project root. Key configuration sections:

• Theme: Material theme with custom colors and features
• Navigation: Structured site navigation
• Plugins: Documentation generation and enhancement plugins
• Markdown extensions: Enhanced Markdown syntax support

Auto-Generated Documentation

API documentation is automatically generated from Python source code using mkdocstrings. The generation script is located at:

docs/gen_ref_pages.py

This script scans the ccproxy/ package and generates documentation pages for all modules, classes, and functions.

Custom Styling

Custom CSS and JavaScript are included for enhanced functionality:

• docs/assets/extra.css: Custom styling for API endpoints, status codes, and layout
• docs/assets/extra.js: Interactive features like copy buttons and navigation enhancements

GitHub Actions

Automated documentation building and deployment is configured in:

.github/workflows/docs.yml

This workflow:

• Builds documentation on every push to main/dev branches
• Deploys to GitHub Pages automatically
• Runs link checking and validation
• Supports manual deployment triggers

Commands Reference

Taskfile Commands

./Taskfile docs-install   # Install documentation dependencies
./Taskfile docs-serve     # Start development server
./Taskfile docs-build     # Build static documentation
./Taskfile docs-clean     # Clean build artifacts
./Taskfile docs-deploy    # Deploy documentation (GitHub Pages)

Direct MkDocs Commands

# Install dependencies
uv sync --group docs

# Development server
mkdocs serve --dev-addr 127.0.0.1:8080

# Build documentation
mkdocs build --clean

# Deploy to GitHub Pages
mkdocs gh-deploy

Contributing to Documentation

Adding New Pages

1. Create a new Markdown file in the appropriate directory
2. Add the page to the navigation in mkdocs.yml
3. Follow the existing styling conventions
4. Test locally with ./Taskfile docs-serve

Updating API Documentation

API documentation is automatically generated from source code. To update:

1. Add/update docstrings in Python source files
2. Use Google-style docstrings for best formatting
3. Rebuild documentation to see changes

Style Guidelines

• Use clear, concise language
• Include practical examples
• Follow the existing structure and formatting
• Use code blocks with appropriate language tags
• Include navigation links between related pages

Troubleshooting

Common Issues

1. Build errors: Check that all dependencies are installed with ./Taskfile docs-install
2. Missing pages: Ensure new pages are added to the navigation in mkdocs.yml
3. Broken links: Use relative paths and check link targets exist
4. Styling issues: Check custom CSS in docs/assets/extra.css

Development Tips

• Use mkdocs serve for live reload during development
• Check the browser console for JavaScript errors
• Validate Markdown syntax before committing
• Test on both desktop and mobile viewports

Resources

• MkDocs Documentation
• Material for MkDocs
• mkdocstrings Documentation
• Markdown Guide

For questions about the documentation system, please open an issue in the GitHub repository.