docs(api): publish Doxygen API reference to GitHub Pages + ADR-0027 (M7.1)

.github/workflows/docs-site.yml

@@ -0,0 +1,83 @@
+name: docs-site
+
+# Builds the Doxygen API-reference site and publishes it to GitHub Pages
+# (ADR-0027). On pull requests the build runs as a warn-as-error gate only
+# (ADR-0013 §5) — no deploy, so PRs are never blocked by Pages configuration.
+# On push to master the same build's output is published to Pages.
+
+on:
+  pull_request:
+    paths:
+      - 'src/main/cpp/it/d4np/memorypool/**.h'
+      - 'src/main/cpp/it/d4np/memorypool/**.hpp'
+      - 'docs/doxygen/**'
+      - '.github/workflows/docs-site.yml'
+  push:
+    branches: [master]
+    paths:
+      - 'src/main/cpp/it/d4np/memorypool/**.h'
+      - 'src/main/cpp/it/d4np/memorypool/**.hpp'
+      - 'docs/doxygen/**'
+      - '.github/workflows/docs-site.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build API docs (warn-as-error gate)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Doxygen
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends doxygen
+          doxygen --version
+
+      - name: Generate API reference (PROJECT_NUMBER from version.hpp)
+        run: |
+          set -euo pipefail
+          ver=$(sed -n 's/.*PBR_MEMORY_POOL_VERSION_STRING[^"]*"\([^"]*\)".*/\1/p' \
+              src/main/cpp/it/d4np/memorypool/version.hpp)
+          if [ -z "$ver" ]; then
+            echo "::error::could not extract PBR_MEMORY_POOL_VERSION_STRING from version.hpp"
+            exit 1
+          fi
+          echo "Building docs for version $ver"
+          # Doxygen creates OUTPUT_DIRECTORY's leaf but not its missing parent,
+          # and a fresh CI checkout has no build/ dir — create it up front.
+          mkdir -p build/doxygen
+          # WARN_AS_ERROR = FAIL_ON_WARNINGS in the Doxyfile makes any doc
+          # warning fail this step — the M7.1 / ADR-0013 §5 gate.
+          ( cat docs/doxygen/Doxyfile; echo "PROJECT_NUMBER = $ver" ) | doxygen -
+          test -f build/doxygen/html/index.html
+
+      - name: Upload Pages artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build/doxygen/html
+
+  deploy:
+    name: Deploy to GitHub Pages
+    # Deploy only off master / manual dispatch — never from a PR.
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    # Serialize deploys; never cancel an in-progress deployment.
+    concurrency:
+      group: pages
+      cancel-in-progress: false
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

CHANGELOG.md

@@ -18,6 +18,27 @@ under *Changed* or *Removed*.
 The `Unreleased` block accumulates entries during development and is rolled into a
 dated version block (`## [X.Y.Z] — YYYY-MM-DD`) when a release PR closes a milestone.
 
+### Added (M7.1)
+
+- **Doxygen-generated API reference published as a static site** ([ADR-0027](docs/adr/0027-doxygen-html-site-and-publication-pipeline.md), ROADMAP §7.1). A
+  checked-in partial Doxyfile ([`docs/doxygen/Doxyfile`](docs/doxygen/Doxyfile)) and a
+  hand-written landing page ([`docs/doxygen/mainpage.md`](docs/doxygen/mainpage.md)) drive
+  a dependency-free Doxygen HTML build (built-in theme + treeview, no Graphviz, no Python
+  doc stack) over the public-header contract surface only. `PROJECT_NUMBER` is injected at
+  build time from `version.hpp` so the version string stays single-sourced.
+- **`docs-site` CI workflow** ([`.github/workflows/docs-site.yml`](.github/workflows/docs-site.yml)) — builds the
+  reference as a **warn-as-error gate on every PR** (`WARN_AS_ERROR = FAIL_ON_WARNINGS`,
+  refining the ADR-0013 §5 expectation to gate documentation *correctness* — doc-rot,
+  stale `@param`, broken refs — not exhaustiveness) and **publishes to GitHub Pages on
+  push to `master`** via the official `upload-pages-artifact` / `deploy-pages` Actions.
+- README gains a `docs-site` build badge and a pointer to the published API reference.
+
+### Changed (M7.1)
+
+- Three public-header Doxygen comments use the `%` auto-link escape
+  (`::%operator new` / `::%operator delete`) to silence spurious unresolved-link warnings
+  on the global operators under the new warn-as-error gate. No API or behavior change.
+
 ## [0.6.0] — 2026-06-14
 
 **Milestone 6 — Observability & Decorators.** Optional logging / statistics / tracing

README.md

@@ -2,6 +2,7 @@
 
 [![ci](https://github.com/danielPoloWork/pbr-cpp-memory-pool/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/danielPoloWork/pbr-cpp-memory-pool/actions/workflows/ci.yml)
 [![docs](https://github.com/danielPoloWork/pbr-cpp-memory-pool/actions/workflows/docs.yml/badge.svg)](https://github.com/danielPoloWork/pbr-cpp-memory-pool/actions/workflows/docs.yml)
+[![docs-site](https://github.com/danielPoloWork/pbr-cpp-memory-pool/actions/workflows/docs-site.yml/badge.svg)](https://github.com/danielPoloWork/pbr-cpp-memory-pool/actions/workflows/docs-site.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Standard: C++17 / ANSI C](https://img.shields.io/badge/Standard-C%2B%2B17%20%2F%20ANSI%20C-blue.svg)](docs/specs/01_spec_cpp_memory_pool.md)
 [![Status: v0.6.0 observability](https://img.shields.io/badge/Status-v0.6.0%20observability-green.svg)](https://github.com/danielPoloWork/pbr-cpp-memory-pool/releases/tag/v0.6.0)
@@ -37,6 +38,8 @@ void           memory_pool_destroy(memory_pool_t* pool);
 
 A C++17 RAII wrapper (`it::d4np::memorypool::Pool`) and a typed template (`TypedPool<T>`) layer on top of this surface — see Milestones 2.5 and 3.2 in [`ROADMAP.md`](ROADMAP.md).
 
+The complete, cross-linked **API reference** — every public symbol's parameter / return / throws contract — is generated from the in-header Doxygen comments and published to [GitHub Pages](https://danielpolowork.github.io/pbr-cpp-memory-pool/) on every push to `master` ([ADR-0027](docs/adr/0027-doxygen-html-site-and-publication-pipeline.md)). The same build runs as a warn-as-error gate on every PR.
+
 ## Architecture
 
 The pool manages free memory using a **free list embedded inside the free blocks themselves**: when a block is free, its first `sizeof(void*)` bytes hold the address of the next free block. Live blocks carry no metadata at all.
@@ -109,7 +112,7 @@ Every PR must clear, at minimum:
 | Public API docs               | Doxygen-compatible, builds without warnings                                  |
 | Performance claims            | Backed by reproducible benchmark under `src/bench/`                          |
 
-Full quality contract: [`AGENTS.md`](AGENTS.md) §10. The C++ build matrix, sanitizers, `clang-format`, `clang-tidy` diff gate, ANSI C / C99 verification, and zero-external-dependency audit run on every PR via [`ci.yml`](.github/workflows/ci.yml); a docs-only workflow ([`docs.yml`](.github/workflows/docs.yml)) covers markdownlint, internal link checks, and ADR numbering sanity. Both badges above gate `master`.
+Full quality contract: [`AGENTS.md`](AGENTS.md) §10. The C++ build matrix, sanitizers, `clang-format`, `clang-tidy` diff gate, ANSI C / C99 verification, and zero-external-dependency audit run on every PR via [`ci.yml`](.github/workflows/ci.yml); a docs-only workflow ([`docs.yml`](.github/workflows/docs.yml)) covers markdownlint, internal link checks, and ADR numbering sanity; a docs-site workflow ([`docs-site.yml`](.github/workflows/docs-site.yml)) builds the Doxygen API reference as a warn-as-error gate on every PR and publishes it to GitHub Pages on push to `master` ([ADR-0027](docs/adr/0027-doxygen-html-site-and-publication-pipeline.md)). The badges above gate `master`.
 
 ## Build and test
 

ROADMAP.md

@@ -108,7 +108,7 @@ Goal: optional logging / statistics / tracing without touching the hot path of r
 
 Goal: ship a v1.0.0 reference implementation.
 
-- [ ] 7.1 Doxygen-generated API documentation published as a static site.
+- [x] 7.1 Doxygen-generated API documentation published as a static site. Implemented per [ADR-0027](docs/adr/0027-doxygen-html-site-and-publication-pipeline.md), closing the rendering half that [ADR-0013](docs/adr/0013-doxygen-for-api-markdown-for-narrative.md) §4–§5 deferred to this item. A checked-in **partial** Doxyfile ([`docs/doxygen/Doxyfile`](docs/doxygen/Doxyfile)) plus a hand-written landing page ([`docs/doxygen/mainpage.md`](docs/doxygen/mainpage.md)) drive a **dependency-free** Doxygen HTML build — built-in theme with `GENERATE_TREEVIEW`, no Graphviz (`HAVE_DOT = NO`), no vendored CSS, no Python doc stack (the MkDocs/Sphinx-Breathe unified narrative site sketched in ADR-0013 §4 is explicitly **deferred post-v1.0**, consistent with spec §3.3). `INPUT` is the public-header contract surface only (`*.h` + `*.hpp` under `src/main/cpp/it/d4np/memorypool/`, `EXTRACT_PRIVATE = NO`), with `PBR_MEMORY_POOL_DIAGNOSTICS=1` predefined so the ADR-0019 free-list iterator surface renders. **The warn-as-error gate refines ADR-0013 §5**: `WARN_AS_ERROR = FAIL_ON_WARNINGS` + `WARN_IF_DOC_ERROR = YES` fail CI on the *doc-rot* class (malformed commands, unresolved cross-references, stale `@param` names) while `WARN_IF_UNDOCUMENTED` / `WARN_NO_PARAMDOC` stay **off** — gating documentation *correctness*, not ceremonial *exhaustiveness* on every operator and trait typedef (ADR-0027 §3). `PROJECT_NUMBER` is left blank and **injected at build time from `version.hpp`** so the version string stays single-sourced. A new workflow ([`.github/workflows/docs-site.yml`](.github/workflows/docs-site.yml)) builds the site as a **warn-as-error gate on every PR** (no deploy — PRs are never blocked by Pages configuration) and **publishes to GitHub Pages on push to `master`** via the official `upload-pages-artifact` / `deploy-pages` Actions (no generated HTML committed; `build/` is git-ignored). Three public-header comments gain the Doxygen `%` auto-link escape (`::%operator new` / `::%operator delete`) to silence spurious unresolved-link warnings on the global operators. Verified locally with Doxygen 1.10.0: zero warnings, `build/doxygen/html/index.html` generated. **One-time maintainer action:** enable GitHub Pages with *Source: GitHub Actions* in repository settings before the first `master` deploy (the PR gate works regardless).
 - [ ] 7.2 README: full usage example, performance summary, compatibility matrix.
 - [ ] 7.3 `CHANGELOG.md` audit for the v1.0.0 entry: consolidate every Unreleased line accumulated since `v0.6.0`, verify category placement, and write the v1.0.0 summary headline (the file itself was introduced in Milestone 1.12).
 - [ ] 7.4 ADR: install / packaging layout (public-header export, pkg-config, CMake `find_package` config file) — phase 1 distribution per ADR-0004 §5.