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¶

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

Updating API Documentation¶

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

Add/update docstrings in Python source files
Use Google-style docstrings for best formatting
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¶

Build errors: Check that all dependencies are installed with ./Taskfile docs-install
Missing pages: Ensure new pages are added to the navigation in mkdocs.yml
Broken links: Use relative paths and check link targets exist
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¶

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