PineForge documentation site

The API reference at https://cdocs.pineforge.dev, generated by Doxygen with the doxygen-awesome-css theme and hosted on Cloudflare Pages.

Layout

docs/
├── Doxyfile              # Doxygen config: INPUT, theme, options. Every page
│                         # under pages/ is listed there; the order is ours.
├── build.sh              # one-shot: fetch theme, run doxygen -> docs/site/html/,
│                         # then fail on a warning in the guarded public surface
├── groups.dox            # the two layer groups, kernel and Pine adapter
├── ci.md                 # the CI profiles, the parity gate, the doc guards
├── coverage.md           # the canonical Pine v6 coverage map
├── pine_v6_audit_master.md, pine_v6_coverage_detail.md
│                         # the per-builtin inventory the coverage map summarises
├── pages/                # the narrative pages (33 files; see the site index)
│   ├── index.md             # @mainpage, and the index of every page
│   ├── public-contract.md   # what the version number promises from 1.0.0
│   ├── native-engine.md     # the native host reference
│   ├── pine-to-native.md    # the Pine -> native migration map
│   ├── contributing-llm.md  # contributor onboarding written for an agent
│   └── …                    # lifecycle, streaming, metrics, magnifier, MTF, …
├── design/
│   └── native-feature-parity.md   # the inventory every boundary ruling is measured against
├── adr/
│   └── 0001-kernel-adapter-boundary.md   # the kernel/adapter boundary and its ruling tables
├── _theme/
│   ├── header.html, footer.html, custom.css
│   └── doxygen-awesome/   # fetched at build time (gitignored)
└── site/                  # build output (gitignored)
    └── html/

The loose *.md files directly under docs/ that are not listed above (native-settlement.md, pine-adapter-kernel-notes.md, native-refactor-progress.md, the boundary notes) are engineering records rather than published pages. Only native-settlement.md, design/ and adr/ are in the Doxyfile INPUT; the rest are read in the repository.

Build locally

# Prereqs: doxygen, graphviz
brew install doxygen graphviz          # macOS
# sudo apt install doxygen graphviz    # Linux

bash docs/build.sh
python3 -m http.server -d docs/site/html 8080
# open http://localhost:8080/

The first build fetches doxygen-awesome-css v2.3.4 (~150 KB) into docs/_theme/doxygen-awesome/; later builds skip the download.

build.sh does not fail on every Doxygen warning — one stale comment in a legacy adapter header would then stop the site from building. It fails on a warning in the guarded surface instead: the kernel and native API headers, the two C headers, groups.dox and examples/native/. Warnings anywhere else are printed and counted.

Editing

• API reference — add Doxygen comments (/** … */) to declarations in the public headers; they are extracted automatically.

• A new narrative page — put it under docs/pages/, give it a # Title {#anchor} first line so other pages can @ref anchor it, register it in the Doxyfile INPUT list, and add a row to the page index at the bottom of pages/index.md.

• Citations — cite the tree with the symbol in backticks immediately before a path and line number:

  ... one `NativeRunSpec` native_run_spec.hpp:490 names the clock ...
  

  That is an anchor. scripts/check_doc_anchors.py checks that the cited line still holds the claimed symbol, and --fix re-anchors the unambiguous ones after a header moves. The full grammar is that script's own docstring.

The documentation guards

Three checks run over the published pages. They are described in full, with what each refuses, in docs/ci.md.

python3 scripts/check_doc_anchors.py             # every file:line resolves to its symbol
python3 scripts/check_doc_lint.py                # no stale epoch, roadmap label or dead link
python3 scripts/check_pine_to_native_coverage.py # every Pine builtin has a migration row

All three run as binding stages in scripts/ci_preflight.py. The design inventory guard and detached-comment ceiling run there too.

Deployment (Cloudflare Pages)

The .github/workflows/docs.yml workflow builds and deploys on every push to main and every v* tag.

One-time setup

1. Create a Cloudflare Pages project (any name; default pineforge-docs). Use Direct Upload as the connection method — no Git integration needed; the workflow pushes via Wrangler.

2. In the repo, add these secrets and (optionally) a variable:

   Kind	Name	Value
   Secret	CLOUDFLARE_API_TOKEN	Token with Cloudflare Pages: Edit permission (create here).
   Secret	CLOUDFLARE_ACCOUNT_ID	Found in the right sidebar of the Cloudflare dashboard.
   Variable	CF_PAGES_PROJECT	Pages project name. Optional — defaults to pineforge-docs.

3. Push to main (or run Actions → docs → Run workflow). The site appears at https://<project>.pages.dev/.

Custom domain

Add a CNAME or A record in Cloudflare DNS, then map it under the Pages project's Custom domains tab. No build-side changes needed.

If you would rather host on GitHub Pages, swap the cloudflare/wrangler-action step for actions/deploy-pages@v4 plus actions/upload-pages-artifact@v3 — the build output (docs/site/html) is identical.