[wdconinc]

Briefly, what does this PR introduce?

A Doxygen API reference for algorithms, set up like the one for EDM4eic:

• docs/Doxyfile.in, configured by CMake into build/Doxyfile. README.md is the main page. Since the headers have no doc comments yet, it documents all entities, includes source browsing, and draws class and include diagrams.
• The doxygen-awesome sidebar theme (v2.5.0, MIT, vendored in docs/), with a custom header that links to this repo.
• A GENERATE_DOCS CMake option (default OFF) that adds a docs target:

  cmake -B build -S . -DGENERATE_DOCS=ON
  cmake --build build --target docs

• A build-docs CI job that runs in eic-shell, which already ships doxygen and graphviz, and uploads the HTML as a docs artifact on every run. A deploy-docs job publishes it to GitHub Pages from main.
• README: a Documentation section, and <code>AlgorithmSvc</code> changed to backticks so the heading renders in doxygen.

Tested locally in eic_xl:nightly. The only doxygen warnings are about the fmt::formatter/fmt::is_range specializations in property.h, whose enclosing fmt namespace isn't in the input.

Before merging

Repository settings → Pages → Source must be set to GitHub Actions, or deploy-docs will fail on main.

What kind of change does this PR introduce?

• Bug fix
• New feature (documentation)
• Breaking change

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

An unresolved moderate finding remains, where an explicit GENERATE_DOCS=ON with missing Doxygen only emits a STATUS message and later causes a cryptic build failure on the docs target.

1 open issue

• Missing Doxygen leaves docs target undefined until build time · New

What changed in this PR

This PR adds a Doxygen-based API reference for the algorithms framework and wires it up for automated publishing to GitHub Pages, mirroring the setup used by EDM4eic. Since the headers currently lack doc comments, Doxygen is configured to document all entities with source browsing and class/include diagrams, themed with the vendored doxygen-awesome sidebar theme. It fits into the existing CMake build (via a new GENERATE_DOCS option and docs target) and the existing eic-shell CI workflow (via new build-docs/deploy-docs jobs).

Changes:

• Added Doxygen config (docs/Doxyfile.in, configured by CMake), the vendored doxygen-awesome theme + custom header/CSS, and a GENERATE_DOCS CMake option that defines a docs target.
• Added build-docs (artifact on every run) and deploy-docs (Pages publish from main) CI jobs.
• Added a README "Documentation" section and switched the AlgorithmSvc heading to backticks for correct Doxygen rendering.

File	Description
README.md	Adds a Documentation section with local build steps; switches <code> to backticks so the heading renders in Doxygen.
docs/​Doxyfile.in	CMake-templated Doxygen config; output build/docs/html, README as main page, diagrams enabled.
docs/​doxygen-custom/​header.html	Custom HTML header with GitHub corner link and OpenGraph metadata.
docs/​doxygen-custom/​custom.css	Small custom styles for the GitHub corner and project number spacing.
docs/​doxygen-awesome.css	Vendored third-party theme (MIT) — not reviewed for style.
docs/​doxygen-awesome-sidebar-only.css	Vendored third-party sidebar theme (MIT); --side-nav-fixed-width: 335px matches TREEVIEW_WIDTH.
CMakeLists.txt	Adds GENERATE_DOCS option, configures the Doxyfile, and defines the docs custom target.
.github/​workflows/​linux-eic-shell.yml	Adds build-docs and deploy-docs jobs; reuses existing env vars and action versions.

I found the PR to be in good shape overall. The output path (build/docs/html/) is consistent across the Doxyfile, CMake, CI artifact, and README; the workflow-level env variables and action versions are consistent with existing usage in the same file; and the vendored theme files are properly license-headered. I left one optional best-practices note on the CMake fallback message when Doxygen is missing.

_{Review effort: Balanced}