Fix doc generation and improve on structure + some content

[Ozaq]

Description

commit 9e1dbd5 (HEAD -> fix/doc-structure, origin/fix/doc-structure)
Author: Kai Kratz Kai.Kratz@ecmwf.int
Date: Tue Feb 24 22:02:52 2026 +0100

Fix ninja not detecting RST file changes

file(GLOB_RECURSE) only runs at configure time, so adding or
renaming RST files left ninja with a stale dependency list that
reported "nothing to do." CONFIGURE_DEPENDS makes ninja re-check
the glob at each build and reconfigure when the file set changes.

Also filters out the leftover in-source _build/ directory whose
stale RST copies were polluting the dependency list.

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

commit bd89f27
Author: Kai Kratz Kai.Kratz@ecmwf.int
Date: Tue Feb 24 21:44:58 2026 +0100

Add fdb wrapper section and tool summary tables to CLI docs

Users landing on the CLI tools page had no overview of what's
available — they had to click into each page. Tables with one-line
descriptions let users scan and find the right tool quickly.

Moves the fdb wrapper command to its own prominent section so new
users understand the single entry point before diving into
individual tools.

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

commit ecaedf4
Author: Kai Kratz Kai.Kratz@ecmwf.int
Date: Tue Feb 24 21:27:13 2026 +0100

Replace build_docs.sh with native CMake doc build

The shell script had a broken INPUT path (resolved relative to
docs/ instead of the repo root), used readlink -f which doesn't
exist on stock macOS, and ran doxygen+sphinx as one opaque step
so CMake couldn't skip doxygen when only RST files changed.

Native configure_file() + add_custom_command() fixes all three
and uses PROJECT_SOURCE_DIR to work correctly in super-builds.

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

commit cd2fcc5
Author: Kai Kratz Kai.Kratz@ecmwf.int
Date: Tue Feb 24 21:27:00 2026 +0100

Flatten doc structure to match how users discover tools

The three-category split (DebugTools, GeneralPurposeTools,
SpecialPurposeTools) forced users to know a tool's classification
before finding its docs. A flat cli_tools/ directory lets users
scan all tools in one place and matches the single --help index.

Consolidates the C and C++ API pages into one breathe-backed page
so the reference stays in sync with headers automatically.

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

Contributor Declaration

By opening this pull request, I affirm the following:

• All authors agree to the Contributor License Agreement.
• The code follows the project's coding standards.
• I have performed self-review and added comments where needed.
• I have added or updated tests to verify that my changes are effective and functional.
• I have run all existing tests and confirmed they pass.

🌈🌦️📖🚧 Documentation Z3FDB 🚧📖🌦️🌈
https://sites.ecmwf.int/docs/dev-section/z3fdb/pull-requests/PR-233

🌈🌦️📖🚧 Documentation FDB 🚧📖🌦️🌈
https://sites.ecmwf.int/docs/dev-section/fdb/pull-requests/PR-233

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 71.19%. Comparing base (aa3e626) to head (f00d208).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop     #233   +/-   ##
========================================
  Coverage    71.18%   71.19%           
========================================
  Files          376      376           
  Lines        23709    23709           
  Branches      2476     2477    +1     
========================================
+ Hits         16877    16879    +2     
+ Misses        6832     6830    -2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Ozaq]

Code review

Found 1 issue:

1. build_docs.sh does not substitute @FDB_VERSION@ in the Doxyfile. The sed command on lines 16-19 substitutes @DOXYGEN_OUTPUT_DIR@ and @DOXYGEN_INPUT_DIR@, but @FDB_VERSION@ (introduced in Doxyfile.in at line 51) is never replaced -- despite version_str already being read from VERSION on line 6. The CMake configure_file() path handles all three correctly; only the shell script path is broken. Anyone building docs via build_docs.sh (including CI) will see the literal string @FDB_VERSION@ as the Doxygen PROJECT_NUMBER.

fdb/docs/fdb/build_docs.sh

Lines 5 to 19 in c737feb

	repo_root="$(cd "${script_dir}/../.." && pwd)"
	version_str=$(cat "${repo_root}/VERSION")
	output_dir=${DOCBUILD_OUTPUT:-doc-build}
	doxygen_output_dir="${output_dir}/doxygen"
	doxygen_input_dir="${repo_root}/src/fdb5/api"
	doxygen_executable="${DOXYGEN_EXECUTABLE:-doxygen}"
	sphinx_executable="${SPHINX_EXECUTABLE:-sphinx-build}"
	# Substitute CMake @VARIABLE@ placeholders in Doxyfile.in
	mkdir -p "${doxygen_output_dir}"
	sed \
	-e "s|@DOXYGEN_OUTPUT_DIR@|${doxygen_output_dir}|g" \
	-e "s|@DOXYGEN_INPUT_DIR@|${doxygen_input_dir}|g" \
	"${script_dir}/Doxyfile.in" > "${output_dir}/Doxyfile"

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}