tools-only 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 layoutdocs/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 servefor 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.