Ray's Knowledge Base

doxygen docs/Doxyfile from the repo root writes a stray doxygen/ folder

PitfallVerified 27 Sep 2026Holds project: dftracer-utils
Pitfall. The symptom, what causes it, and the fix that was run and seen to work.

Symptom#

After running the op-parity recipe from the repo root, an untracked doxygen/xml/ folder appears at the top of the repository, and scripts/check_op_parity_doxygen.py docs/doxygen/xml ... reads a folder that this doxygen run did not write.

Cause#

docs/Doxyfile sets OUTPUT_DIRECTORY = doxygen, which is relative to the working directory. docs/source/conf.py runs doxygen with cwd set to docs/, so the expected output is docs/doxygen/xml (gitignored as docs/doxygen/). The command CLAUDE.md gave before 2026-09-27 (doxygen docs/Doxyfile from the root) writes ./doxygen/ instead.

Fix#

Never run doxygen by hand. Build the docs with Sphinx, which runs doxygen from docs/ and writes docs/doxygen/xml, then run scripts/check_op_parity_doxygen.py docs/doxygen/xml build/build-tests/lib/libdftracer_utils_dataframe.dylib. The user's rule (2026-09-27): everything is driven by Sphinx inside docs/; AGENTS.md (CLAUDE.md) now says so. Delete a stray root doxygen/ folder if one was made.

Evidence#

  • 2026-09-27, duql stage 12a1: doxygen docs/Doxyfile from the root created doxygen/xml (untracked, 15:34); the parity check passed on docs/doxygen/xml from the Sphinx run.