docs Directory Reference

Detailed Description

This directory contains documentation source files and generated API documentation.

Directory Structure

docs/
├── README.md              # This file
├── DOXYGEN_SETUP.md       # Doxygen setup and usage guide
├── generate_docs.sh       # Script to build and deploy documentation
├── images/                # Images for documentation
└── html/                  # Generated HTML documentation (auto-generated)

Quick Start

Generate Documentation

Run the convenience script to build and deploy documentation:

cd docs
./generate_docs.sh

This script will:

1. Run make docs from the build directory
2. Copy the generated HTML to docs/html/
3. Display the location and size of the documentation
4. Optionally open it in your browser

Manual Generation

If you prefer to generate documentation manually:

cd build
cmake .. -DBUILD_DOCUMENTATION=ON
make docs

Documentation will be generated in build/docs/html/.

View Documentation

After generation, open the documentation:

# Using the generated copy in docs/
xdg-open docs/html/index.html
 
# Or from the build directory
xdg-open build/docs/html/index.html

Documentation Structure

The generated documentation includes:

• Classes: All C++ classes from EmberCore and EmberForge
• Namespaces: Organized namespace documentation
• Files: Source code browser with syntax highlighting
• File Documentation: Header and source file documentation

Adding Documentation

To add documentation to your code, use Doxygen-style comments:

Class Documentation

class MyClass {
public:
    int myMethod(int param1, const std::string& param2);
};

File Documentation

At the top of your source files:

Additional Pages

To add custom documentation pages, create markdown files in this docs/ directory and they will be automatically included in the generated documentation.

Configuration

Documentation configuration is stored in:

• Doxyfile.in - Main Doxygen configuration template (in project root)
• CMakeLists.txt - Build system integration (in project root)

To modify documentation settings:

1. Edit Doxyfile.in
2. Reconfigure: cmake .. -DBUILD_DOCUMENTATION=ON
3. Rebuild: make docs

Theme

The documentation uses the doxygen-awesome-css theme with sidebar-only layout for a modern, clean appearance. The theme is automatically downloaded during CMake configuration.

Theme features:

• Modern, responsive design
• Sidebar navigation with tree view
• Search functionality
• Mobile-friendly
• Clean, professional appearance

Troubleshooting

Documentation not generating

Make sure BUILD_DOCUMENTATION is enabled:

cmake .. -DBUILD_DOCUMENTATION=ON

Doxygen not found

The build system will automatically download and build Doxygen 1.9.8 if not found. This happens once and takes ~5-10 minutes.

Missing content

Make sure your code has Doxygen comments. Enable EXTRACT_ALL in Doxyfile.in to document all code regardless of comments (currently enabled).

More Information

See DOXYGEN_SETUP.md for detailed setup instructions and configuration options.