Add docs support
Some checks failed
CI/CD Pipeline / Code Linting (push) Failing after 24s
CI/CD Pipeline / Build and Test (Debug, clang, ubuntu-latest) (push) Failing after 5m17s
CI/CD Pipeline / Build and Test (Debug, gcc, ubuntu-latest) (push) Failing after 5m32s
CI/CD Pipeline / Build and Test (Release, clang, ubuntu-20.04) (push) Failing after 5m45s
CI/CD Pipeline / Build and Test (Release, clang, ubuntu-latest) (push) Failing after 5m12s
CI/CD Pipeline / Build and Test (Release, gcc, ubuntu-20.04) (push) Failing after 5m22s
CI/CD Pipeline / Build and Test (Release, gcc, ubuntu-latest) (push) Failing after 5m26s
CI/CD Pipeline / Docker Build Test (push) Failing after 1m7s
CI/CD Pipeline / Performance Benchmarks (push) Has been skipped
CI/CD Pipeline / Build Documentation (push) Failing after 18s
CI/CD Pipeline / Create Release Package (push) Has been skipped
Some checks failed
CI/CD Pipeline / Code Linting (push) Failing after 24s
CI/CD Pipeline / Build and Test (Debug, clang, ubuntu-latest) (push) Failing after 5m17s
CI/CD Pipeline / Build and Test (Debug, gcc, ubuntu-latest) (push) Failing after 5m32s
CI/CD Pipeline / Build and Test (Release, clang, ubuntu-20.04) (push) Failing after 5m45s
CI/CD Pipeline / Build and Test (Release, clang, ubuntu-latest) (push) Failing after 5m12s
CI/CD Pipeline / Build and Test (Release, gcc, ubuntu-20.04) (push) Failing after 5m22s
CI/CD Pipeline / Build and Test (Release, gcc, ubuntu-latest) (push) Failing after 5m26s
CI/CD Pipeline / Docker Build Test (push) Failing after 1m7s
CI/CD Pipeline / Performance Benchmarks (push) Has been skipped
CI/CD Pipeline / Build Documentation (push) Failing after 18s
CI/CD Pipeline / Create Release Package (push) Has been skipped
This commit is contained in:
191
DOCUMENTATION_SETUP.md
Normal file
191
DOCUMENTATION_SETUP.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# Documentation Setup Summary
|
||||
|
||||
This document summarizes the documentation system setup for the SVM Classifier C++ project.
|
||||
|
||||
## 📁 Files Created/Modified
|
||||
|
||||
### New Files
|
||||
- `Doxyfile.in` - Doxygen configuration template with CMake variables
|
||||
- `build_docs.sh` - Standalone documentation build script
|
||||
|
||||
### Modified Files
|
||||
- `CMakeLists.txt` - Added Doxygen target and configuration
|
||||
- `validate_build.sh` - Added documentation validation
|
||||
- `.github/workflows/ci.yml` - Added documentation build and GitHub Pages deployment
|
||||
- `examples/CMakeLists.txt` - Added advanced_usage target
|
||||
- `README.md` - Added documentation build instructions
|
||||
|
||||
## 🎯 CMake Documentation Target
|
||||
|
||||
### Configuration Variables
|
||||
The system automatically configures these CMake variables in `Doxyfile.in`:
|
||||
|
||||
```cmake
|
||||
@PROJECT_NAME@ # Project name from CMakeLists.txt
|
||||
@PROJECT_VERSION@ # Version from CMakeLists.txt
|
||||
@PROJECT_DESCRIPTION@ # Project description
|
||||
@CMAKE_SOURCE_DIR@ # Source directory path
|
||||
@DOXYGEN_OUTPUT_DIR@ # Output directory (build/docs)
|
||||
@DOXYGEN_DOT_FOUND@ # Whether Graphviz is available
|
||||
@DOXYGEN_DOT_PATH@ # Path to Graphviz dot executable
|
||||
```
|
||||
|
||||
### CMake Options
|
||||
```cmake
|
||||
BUILD_DOCUMENTATION=ON # Enable documentation installation
|
||||
```
|
||||
|
||||
### CMake Targets
|
||||
```bash
|
||||
cmake --build build --target doxygen # Build documentation
|
||||
cmake --build build --target docs # Alias for doxygen
|
||||
```
|
||||
|
||||
## 🛠️ Usage Examples
|
||||
|
||||
### Basic Documentation Build
|
||||
```bash
|
||||
# Configure with documentation support
|
||||
mkdir build && cd build
|
||||
cmake .. -DCMAKE_PREFIX_PATH=/opt/libtorch
|
||||
|
||||
# Build documentation
|
||||
cmake --build . --target doxygen
|
||||
|
||||
# Documentation will be in build/docs/html/
|
||||
```
|
||||
|
||||
### Using the Build Script
|
||||
```bash
|
||||
# Simple build
|
||||
./build_docs.sh
|
||||
|
||||
# Build and open in browser
|
||||
./build_docs.sh --open
|
||||
|
||||
# Clean and rebuild
|
||||
./build_docs.sh --clean --open
|
||||
|
||||
# Verbose output
|
||||
./build_docs.sh --verbose
|
||||
```
|
||||
|
||||
### Installation with Documentation
|
||||
```bash
|
||||
# Configure with documentation installation
|
||||
cmake .. -DBUILD_DOCUMENTATION=ON
|
||||
|
||||
# Install (includes documentation)
|
||||
cmake --install . --component documentation
|
||||
```
|
||||
|
||||
## 📊 Features
|
||||
|
||||
### Automatic Configuration
|
||||
- ✅ Project information (name, version, description) from CMakeLists.txt
|
||||
- ✅ Automatic path configuration (source, output directories)
|
||||
- ✅ Graphviz detection for enhanced diagrams
|
||||
- ✅ Warning log file configuration
|
||||
|
||||
### Enhanced Documentation
|
||||
- ✅ Source code browsing with syntax highlighting
|
||||
- ✅ Class diagrams and inheritance graphs (with Graphviz)
|
||||
- ✅ Cross-references and search functionality
|
||||
- ✅ Markdown support for README files
|
||||
- ✅ Example code integration
|
||||
|
||||
### Build Integration
|
||||
- ✅ CMake target for easy building
|
||||
- ✅ Validation in build testing scripts
|
||||
- ✅ CI/CD integration with GitHub Actions
|
||||
- ✅ GitHub Pages deployment
|
||||
|
||||
### Quality Assurance
|
||||
- ✅ Warning detection and reporting
|
||||
- ✅ File existence validation
|
||||
- ✅ Size and completeness checks
|
||||
- ✅ Cross-platform compatibility
|
||||
|
||||
## 🔧 Advanced Configuration
|
||||
|
||||
### Custom Doxyfile Settings
|
||||
The `Doxyfile.in` template can be customized by modifying:
|
||||
|
||||
```doxyfile
|
||||
# Enable/disable specific outputs
|
||||
GENERATE_LATEX = NO # LaTeX output
|
||||
GENERATE_XML = NO # XML output
|
||||
GENERATE_RTF = NO # RTF output
|
||||
|
||||
# Customize appearance
|
||||
HTML_COLORSTYLE_HUE = 220 # Blue theme
|
||||
GENERATE_TREEVIEW = YES # Navigation tree
|
||||
SEARCHENGINE = YES # Search functionality
|
||||
```
|
||||
|
||||
### Additional CMake Variables
|
||||
Add custom variables in CMakeLists.txt:
|
||||
|
||||
```cmake
|
||||
set(PROJECT_AUTHOR "Your Name")
|
||||
set(PROJECT_HOMEPAGE_URL "https://your-site.com")
|
||||
# These will be available as @PROJECT_AUTHOR@ in Doxyfile.in
|
||||
```
|
||||
|
||||
### Output Customization
|
||||
Modify output paths:
|
||||
|
||||
```cmake
|
||||
set(DOXYGEN_OUTPUT_DIR "${CMAKE_BINARY_DIR}/documentation")
|
||||
```
|
||||
|
||||
## 🚀 CI/CD Integration
|
||||
|
||||
### GitHub Actions
|
||||
The workflow automatically:
|
||||
1. Installs Doxygen and Graphviz
|
||||
2. Configures CMake with documentation enabled
|
||||
3. Builds documentation using the CMake target
|
||||
4. Validates generated files
|
||||
5. Deploys to GitHub Pages (on main branch)
|
||||
|
||||
### Local Validation
|
||||
The validation script checks:
|
||||
- Doxygen availability
|
||||
- Successful documentation generation
|
||||
- Warning detection and reporting
|
||||
- Essential file existence
|
||||
- Documentation size verification
|
||||
|
||||
## 📈 Benefits
|
||||
|
||||
### Developer Benefits
|
||||
- **Consistent Documentation**: CMake ensures consistent configuration
|
||||
- **Easy Maintenance**: Template-based approach reduces duplication
|
||||
- **Automated Building**: Integrated with build system
|
||||
- **Quality Assurance**: Automated validation and warning detection
|
||||
|
||||
### User Benefits
|
||||
- **Professional Documentation**: Clean, searchable HTML output
|
||||
- **Visual Diagrams**: Class inheritance and collaboration graphs
|
||||
- **Cross-Referenced**: Easy navigation between related components
|
||||
- **Always Updated**: Automatically generated from source code
|
||||
|
||||
### Project Benefits
|
||||
- **Professional Presentation**: High-quality documentation for releases
|
||||
- **Reduced Maintenance**: Automated generation and deployment
|
||||
- **Better Adoption**: Easy-to-access documentation improves usability
|
||||
- **Quality Metrics**: Documentation warnings help maintain code quality
|
||||
|
||||
## 🎯 Summary
|
||||
|
||||
The documentation system provides:
|
||||
|
||||
1. **Seamless Integration**: Works with existing CMake build system
|
||||
2. **Template-Based Configuration**: Easy customization via Doxyfile.in
|
||||
3. **Automated Building**: Simple `cmake --build . --target doxygen` command
|
||||
4. **Quality Assurance**: Validation and warning detection
|
||||
5. **Professional Output**: Clean HTML documentation with diagrams
|
||||
6. **CI/CD Ready**: Automated building and deployment
|
||||
|
||||
This setup ensures that high-quality documentation is always available and up-to-date with minimal developer effort! 📚✨
|
Reference in New Issue
Block a user