# 2553 Documentation Guide B3c0b700 > Documentation Guide - Skill: `tools-only/2553-documentation-guide-b3c0b700` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tools-only/2553-documentation-guide-b3c0b700` - Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/2553-documentation-guide-b3c0b700/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tools-only (https://skillmd.com/u/tools-only) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/tools-only/2553-documentation-guide-b3c0b700 --- # Documentation Guide This directory contains the source files for the CCProxy API documentation, built with [MkDocs](https://www.mkdocs.org/) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). ## Quick Start ### Prerequisites - Python 3.11+ - uv (preferred) or pip ### Setup and Serve Locally ```bash # 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 ```bash # 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 ```bash ./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 ```bash # 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](https://www.mkdocs.org/) - [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) - [mkdocstrings Documentation](https://mkdocstrings.github.io/) - [Markdown Guide](https://www.markdownguide.org/) --- For questions about the documentation system, please open an issue in the GitHub repository.