docs: add Doxygen API reference with doxygen-awesome-css theme

Convert all public API comments from plain // to Doxygen /// with
@brief, @param, @return, @throws, @tparam, and @see across all four
headers (entitygen.hpp, stats_observer.hpp, entt_adapter.hpp,
flecs_adapter.hpp). Grouped members with @name sections.

Add Doxyfile configured for HTML output with doxygen-awesome-css v2.4.2
theme, README.md as main page, and usage.md included.

Fill usage.md gaps: eg::has(key) in Generator Introspection,
stats_observer::report() and operator<< examples, Error Reference
table covering all thrown exceptions, and cross-link to generated
API docs.

Add Makefile docs target (make docs) and include doc/api in clean.
Add CI step to build documentation on every push/PR and deploy to
GitHub Pages on main via actions/deploy-pages@v4.
Add doc/api/ to .gitignore.

Author: dasmig

.github/workflows/ci.yml

@@ -63,3 +63,29 @@ jobs:
 
       - name: Lint
         run: make lint
+
+      - name: Build documentation
+        run: |
+          sudo apt-get install -y doxygen
+          make docs
+
+      - name: Upload documentation
+        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: doc/api/html
+
+  deploy-docs:
+    needs: build-and-test
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -11,6 +11,9 @@ coverage/
 *.profraw
 *.profdata
 
+# Doxygen output
+doc/api/
+
 # IDE / editor
 .vscode/
 

Doxyfile

@@ -0,0 +1,66 @@
+# Doxyfile for Entity Generator
+# Run: doxygen Doxyfile
+
+PROJECT_NAME           = "Entity Generator"
+PROJECT_NUMBER         = 1.1.0
+PROJECT_BRIEF          = "Composable, deterministic entity generation for C++23"
+PROJECT_LOGO           =
+
+OUTPUT_DIRECTORY       = doc/api
+CREATE_SUBDIRS         = NO
+
+# --- Input ----------------------------------------------------------------
+
+INPUT                  = dasmig/ doc/usage.md README.md
+FILE_PATTERNS          = *.hpp
+RECURSIVE              = YES
+USE_MDFILE_AS_MAINPAGE = README.md
+
+# --- Extraction -----------------------------------------------------------
+
+EXTRACT_ALL            = NO
+EXTRACT_PRIVATE        = NO
+EXTRACT_STATIC         = YES
+
+# --- Source browsing -------------------------------------------------------
+
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = NO
+
+# --- Build ----------------------------------------------------------------
+
+BUILTIN_STL_SUPPORT    = YES
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+PREDEFINED             = DASMIG_ENTITYGEN_HPP \
+                         DASMIG_EXT_STATS_OBSERVER_HPP \
+                         DASMIG_EXT_ENTT_ADAPTER_HPP \
+                         DASMIG_EXT_FLECS_ADAPTER_HPP
+
+# Exclude deps/ (vendored third-party headers).
+EXCLUDE_PATTERNS       = */deps/*
+
+# --- Warnings -------------------------------------------------------------
+
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
+
+# --- Output formats --------------------------------------------------------
+
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+HTML_EXTRA_STYLESHEET  = doc/doxygen-awesome-css/doxygen-awesome.css
+HTML_COLORSTYLE        = LIGHT
+GENERATE_TREEVIEW      = YES
+DISABLE_INDEX          = NO
+FULL_SIDEBAR           = NO
+
+GENERATE_LATEX         = NO
+GENERATE_MAN           = NO
+GENERATE_XML           = NO
+
+# --- Graphs ----------------------------------------------------------------
+
+HAVE_DOT               = NO
+CLASS_DIAGRAMS         = YES

Makefile

@@ -11,7 +11,7 @@ TEST_BIN := $(BUILD)/test_runner
 COV_FLAGS := -fprofile-instr-generate -fcoverage-mapping
 COV_DIR   := coverage
 
-.PHONY: all clean lint test coverage
+.PHONY: all clean lint test coverage docs
 
 all: $(EXAMPLE_BIN)
 
@@ -35,8 +35,12 @@ coverage: $(TEST_SRC) dasmig/entitygen.hpp dasmig/random.hpp | $(BUILD)
 $(BUILD):
 	@mkdir -p $(BUILD)
 
+docs:
+	doxygen Doxyfile
+	@echo "API docs: doc/api/html/index.html"
+
 lint:
 	clang-tidy $(EXAMPLE_SRC) -- $(CXXFLAGS)
 
 clean:
-	rm -rf $(BUILD) $(COV_DIR)
+	rm -rf $(BUILD) $(COV_DIR) doc/api