Auto-generated API doc: doxygen → custom Python emitter → doc/api/.

`cmake --build build --target doc` runs Doxygen to produce XML, then
`doc/gen_api_md.py` (~330 lines, stdlib-only) emits a Markdown tree
under `doc/api/` that gitea renders directly in its file browser.

- 24 class/struct pages + 51 source-file pages + indices, with source
  links of the form `../../../../src/...#L42` that gitea turns into
  clickable line-anchored links.
- Doxyfile.in templated by CMake (XML-only output to build/doc/xml/).
- Pure Python emitter, zero external deps — no doxybook2 (not packaged
  on Arch) and no moxygen (avoids Node).
- Target gracefully disabled if Doxygen or Python 3 is missing at
  configure time; regular build target unaffected.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

CMakeLists.txt

@@ -63,3 +63,38 @@ if(BUILD_TESTING)
     add_test(NAME essim_tests COMMAND essim_tests)
   endif()
 endif()
+
+# Documentation: Doxygen → XML → custom Python script → doc/api/ (Markdown rendered by gitea).
+# Optional — `doc` target is only created if Doxygen and Python 3 are present.
+find_package(Doxygen COMPONENTS doxygen)
+find_package(Python3 COMPONENTS Interpreter)
+
+if(DOXYGEN_FOUND AND Python3_Interpreter_FOUND)
+  set(DOXYGEN_OUTPUT_DIR "${CMAKE_BINARY_DIR}/doc")
+  file(MAKE_DIRECTORY "${DOXYGEN_OUTPUT_DIR}")
+  configure_file(
+    "${CMAKE_SOURCE_DIR}/doc/Doxyfile.in"
+    "${DOXYGEN_OUTPUT_DIR}/Doxyfile"
+    @ONLY)
+
+  set(DOC_API_DIR "${CMAKE_SOURCE_DIR}/doc/api")
+  add_custom_target(doc
+    COMMAND ${CMAKE_COMMAND} -E rm -rf "${DOC_API_DIR}"
+    COMMAND ${CMAKE_COMMAND} -E make_directory "${DOC_API_DIR}/classes"
+    COMMAND ${CMAKE_COMMAND} -E make_directory "${DOC_API_DIR}/files"
+    COMMAND ${DOXYGEN_EXECUTABLE} "${DOXYGEN_OUTPUT_DIR}/Doxyfile"
+    COMMAND ${Python3_EXECUTABLE}
+            "${CMAKE_SOURCE_DIR}/doc/gen_api_md.py"
+            "${DOXYGEN_OUTPUT_DIR}/xml"
+            "${DOC_API_DIR}"
+    WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
+    COMMENT "Generating API documentation (doxygen → gen_api_md.py → doc/api/)"
+    VERBATIM)
+elseif(NOT DOXYGEN_FOUND AND NOT Python3_Interpreter_FOUND)
+  message(STATUS "doc: Doxygen and Python 3 not found — `doc` target disabled.")
+elseif(NOT DOXYGEN_FOUND)
+  message(STATUS "doc: Doxygen not found — `doc` target disabled "
+                 "(install via `pacman -S doxygen`).")
+else()
+  message(STATUS "doc: Python 3 interpreter not found — `doc` target disabled.")
+endif()