121 lines
4.2 KiB
Markdown
121 lines
4.2 KiB
Markdown
# Documentation Directory (`docs/`)
|
|
|
|
This directory contains project documentation, API references, and development guides.
|
|
|
|
## Structure
|
|
|
|
```
|
|
docs/
|
|
├── api/ # API documentation
|
|
│ ├── core/ # Core system API docs
|
|
│ ├── data/ # Data management API
|
|
│ ├── ai/ # AI system API
|
|
│ └── utils/ # Utility API docs
|
|
├── guides/ # Development and usage guides
|
|
│ ├── getting_started.md # Quick start guide
|
|
│ ├── building.md # Build instructions
|
|
│ ├── contributing.md # Contribution guidelines
|
|
│ ├── architecture.md # System architecture
|
|
│ └── performance.md # Performance optimization guide
|
|
├── design/ # Design documents
|
|
│ ├── battle_system.md # Battle system design
|
|
│ ├── data_formats.md # Data format specifications
|
|
│ ├── ai_framework.md # AI system design
|
|
│ └── memory_layout.md # Memory optimization design
|
|
├── examples/ # Code examples and tutorials
|
|
│ ├── basic_battle.md # Simple battle example
|
|
│ ├── custom_ai.md # Creating custom AI
|
|
│ ├── data_loading.md # Loading custom data
|
|
│ └── benchmarking.md # Performance measurement
|
|
├── reference/ # Reference materials
|
|
│ ├── gen1_mechanics.md # Generation 1 battle mechanics
|
|
│ ├── type_chart.md # Type effectiveness reference
|
|
│ ├── move_list.md # Complete move list
|
|
│ └── pokemon_list.md # Complete Pokemon list
|
|
├── assets/ # Documentation assets
|
|
│ ├── images/ # Diagrams and screenshots
|
|
│ ├── diagrams/ # Architecture diagrams
|
|
│ └── data/ # Sample data files
|
|
├── conf.py # Sphinx configuration
|
|
├── index.rst # Main documentation index
|
|
├── Makefile # Documentation build system
|
|
└── requirements.txt # Documentation dependencies
|
|
```
|
|
|
|
## Documentation Tools
|
|
|
|
### Sphinx
|
|
- **Primary Tool**: Sphinx for comprehensive documentation
|
|
- **Theme**: Read the Docs theme for professional appearance
|
|
- **Extensions**: Auto-API generation, math support, code highlighting
|
|
- **Output Formats**: HTML, PDF, ePub
|
|
|
|
### Doxygen
|
|
- **API Documentation**: Automatic C++ API documentation
|
|
- **Integration**: Breathe extension for Sphinx integration
|
|
- **Comments**: Extract documentation from code comments
|
|
- **Diagrams**: Class and call graphs
|
|
|
|
### PlantUML
|
|
- **Diagrams**: System architecture and sequence diagrams
|
|
- **Integration**: Embedded in Sphinx documentation
|
|
- **Version Control**: Text-based diagrams for easy diffing
|
|
|
|
## Key Documents
|
|
|
|
### Getting Started
|
|
- Installation and setup instructions
|
|
- First battle simulation example
|
|
- Basic API usage patterns
|
|
- Common troubleshooting
|
|
|
|
### Architecture Guide
|
|
- System overview and component relationships
|
|
- Data flow and processing pipeline
|
|
- Performance considerations
|
|
- Extension points for customization
|
|
|
|
### API Reference
|
|
- Complete C++ API documentation
|
|
- Usage examples for each component
|
|
- Performance characteristics
|
|
- Thread safety guarantees
|
|
|
|
### Design Documents
|
|
- Detailed system design rationale
|
|
- Alternative approaches considered
|
|
- Future enhancement plans
|
|
- Technical debt and limitations
|
|
|
|
## Building Documentation
|
|
|
|
```bash
|
|
# Install dependencies
|
|
pip install -r docs/requirements.txt
|
|
|
|
# Build HTML documentation
|
|
cd docs
|
|
make html
|
|
|
|
# Build PDF documentation
|
|
make latexpdf
|
|
|
|
# Auto-rebuild on changes
|
|
sphinx-autobuild . _build/html
|
|
```
|
|
|
|
## Contributing to Documentation
|
|
|
|
- **Markdown**: Use Markdown for guides and design docs
|
|
- **reStructuredText**: Use RST for Sphinx integration
|
|
- **Code Examples**: Include working, tested code examples
|
|
- **Diagrams**: Use PlantUML for system diagrams
|
|
- **Screenshots**: Include relevant UI screenshots
|
|
|
|
## Documentation Standards
|
|
|
|
- **Clarity**: Write for developers unfamiliar with the codebase
|
|
- **Examples**: Include practical, runnable examples
|
|
- **Updates**: Keep documentation synchronized with code changes
|
|
- **Review**: All documentation changes should be reviewed
|