f6722d7e84
Replaces the hand-maintained `doc/api/headers.md` with a generated one
sourced from each header's `\file` brief and the public symbols
extracted by Doxygen into XML. The CI workflow regenerates it on every
push to main that touches the public headers.
New files
─────────
* scripts/gen-headers-md.py — parses doc/doxygen/xml/*.xml, groups
headers by directory (CGAL public / CGAL internals / Core), and
writes a markdown table with header path, first-sentence brief, and
the public symbols declared at file scope. Skips `detail::`
namespaces and template-specialisation duplicates.
* scripts/regen-docs.sh — convenience wrapper:
doxygen → gen-headers-md.py → coverage report.
Workflow changes
────────────────
.gitea/workflows/doxygen-pages.yml now:
1. Runs `bash scripts/doxygen-coverage.sh` as an informational step
(no fail threshold yet — the script supports `--threshold N` for
when we're ready).
2. Re-runs `python3 scripts/gen-headers-md.py` and warns if the
file drifted from what's in main (operator should run
`regen-docs.sh` locally before pushing).
Doxyfile hygiene
────────────────
`HTML_TIMESTAMP` was removed in Doxygen 1.10 → replaced with the new
`TIMESTAMP = NO` to silence the obsolete-tag warning.
Effect on the reviewer-facing landing pages
───────────────────────────────────────────
Every improvement to a `\file` brief at the top of a public header now
flows automatically into both:
* the Doxygen HTML at https://tmoussa.codeberg.page/ConformalLabpp/
* the markdown landing at doc/api/headers.md (rendered by Codeberg
in the repo view)
…so writers have a single source of truth (the C++ source) and
readers see the same words in both surfaces.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
16 lines
571 B
Bash
Executable File
16 lines
571 B
Bash
Executable File
#!/bin/sh
|
|
# scripts/regen-docs.sh — convenience wrapper:
|
|
# 1. run doxygen to refresh XML + HTML output
|
|
# 2. regenerate doc/api/headers.md from the XML
|
|
# 3. report coverage so the operator sees the impact
|
|
#
|
|
# Intended for local use ("I just added a \file brief — regenerate
|
|
# the markdown landing page"); the same steps run automatically in
|
|
# .gitea/workflows/doxygen-pages.yml on every push to main that touches
|
|
# the public headers.
|
|
set -eu
|
|
cd "$(dirname "$0")/.."
|
|
doxygen Doxyfile >/dev/null
|
|
python3 scripts/gen-headers-md.py
|
|
bash scripts/doxygen-coverage.sh
|