Skip to content

Commit 16f3652

Browse files
luisleo526claude
andcommitted
Docs: the two site front doors re-derived against HEAD (R5 lane L14-B, item 6)
docs/pages/index.md carried four defects the second audit measured. Its @note called the internal C++ headers "deliberately omitted ... not recommended for direct external consumption" while the migration page tells a native author to include native_host.hpp; it claimed "the entire public surface fits in one header and 65 public PF_API declarations" when it is 65 plus 32 across two; its worked-examples table had zero examples/native/ rows though the tree ships fifteen with CTest rows; and it had no index of its own pages. The page now opens on the two layers and the three front doors, and the @note says what is actually internal: the Pine adapter's own headers. The API section gives both inventories with the guard that pins each. The worked examples are split into driving a compiled strategy and driving the kernel yourself, the second listing every host under examples/native/ with what it demonstrates. A closing index lists all 31 pages under docs/pages/ once, in five groups, each with a one-line description -- including the two that carry no Doxygen label and are therefore named by path. docs/README.md described a docs/ tree that had moved on: a pages/ list of fourteen files (there are 31), no design/ or adr/, no groups.dox, no ci.md, and nothing about the guards a page has to pass. It now describes the tree as it is, says which loose docs/*.md are published and which are engineering records, explains build.sh's scoped warning gate, gives the anchor grammar an editor needs with a worked example, and lists the three documentation guards with their commands and their current binding state. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> (cherry picked from commit a05208056a3da392c8b1c99f63478690a928484c)
1 parent f4ac97c commit 16f3652

2 files changed

Lines changed: 221 additions & 77 deletions

File tree

‎docs/README.md‎

Lines changed: 81 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,75 +1,111 @@
11
# PineForge documentation site
22

3-
OpenCV-style API reference, generated by [Doxygen](https://www.doxygen.nl/)
4-
with the [doxygen-awesome-css](https://jothepro.github.io/doxygen-awesome-css/)
5-
theme. Hosted on Cloudflare Pages.
3+
The API reference at <https://cdocs.pineforge.dev>, generated by
4+
[Doxygen](https://www.doxygen.nl/) with the
5+
[doxygen-awesome-css](https://jothepro.github.io/doxygen-awesome-css/) theme
6+
and hosted on Cloudflare Pages.
67

78
## Layout
89

910
```
1011
docs/
11-
├── Doxyfile # Doxygen config — input, theme, options
12-
├── build.sh # one-shot: fetch theme, run doxygen → docs/site/html/
13-
├── coverage.md # canonical Pine v6 coverage map (also referenced as a page)
14-
├── pages/ # narrative markdown pages
15-
│ ├── index.md # @mainpage — landing
16-
│ ├── getting-started.md
17-
│ ├── install.md
18-
│ ├── integration-cmake.md
19-
│ ├── lifecycle.md
20-
│ ├── streaming.md
21-
│ ├── report-schema.md
22-
│ ├── configuration.md
23-
│ ├── magnifier.md
24-
│ ├── timeframes.md
25-
│ ├── ffi-python.md
26-
│ ├── tutorial-macd.md
27-
│ ├── abi-stability.md
28-
│ └── coverage.md
12+
├── Doxyfile # Doxygen config: INPUT, theme, options. Every page
13+
│ # below is listed there, and the order is ours.
14+
├── build.sh # one-shot: fetch theme, run doxygen -> docs/site/html/,
15+
│ # then fail on a warning in the guarded public surface
16+
├── groups.dox # the @defgroup tree: kernel, Pine adapter, C ABI groups
17+
├── ci.md # the CI profiles, the parity gate, the doc guards
18+
├── coverage.md # the canonical Pine v6 coverage map
19+
├── pine_v6_audit_master.md, pine_v6_coverage_detail.md
20+
│ # the per-builtin inventory the coverage map summarises
21+
├── pages/ # the narrative pages (31 files; see the site index)
22+
│ ├── index.md # @mainpage, and the index of every page
23+
│ ├── native-engine.md # the native host reference
24+
│ ├── pine-to-native.md # the Pine -> native migration map
25+
│ ├── contributing-llm.md # contributor onboarding written for an agent
26+
│ └── … # lifecycle, streaming, metrics, magnifier, MTF, …
27+
├── design/
28+
│ └── native-feature-parity.md # the inventory every boundary ruling is measured against
29+
├── adr/
30+
│ └── 0001-kernel-adapter-boundary.md # the kernel/adapter boundary and its ruling tables
2931
├── _theme/
30-
│ ├── header.html # custom HTML header
31-
│ ├── footer.html
32-
│ ├── custom.css # PineForge color overrides on top of doxygen-awesome
32+
│ ├── header.html, footer.html, custom.css
3333
│ └── doxygen-awesome/ # fetched at build time (gitignored)
3434
└── site/ # build output (gitignored)
3535
└── html/
3636
```
3737

38+
The loose `*.md` files directly under `docs/` that are not listed above
39+
(`native-settlement.md`, `pine-adapter-kernel-notes.md`,
40+
`native-refactor-progress.md`, the boundary notes) are engineering records
41+
rather than published pages. Only `native-settlement.md`, `design/` and `adr/`
42+
are in the Doxyfile `INPUT`; the rest are read in the repository.
43+
3844
## Build locally
3945

4046
```bash
4147
# Prereqs: doxygen, graphviz
42-
brew install doxygen graphviz # macOS
43-
# sudo apt install doxygen graphviz # Linux
48+
brew install doxygen graphviz # macOS
49+
# sudo apt install doxygen graphviz # Linux
4450

4551
bash docs/build.sh
4652
python3 -m http.server -d docs/site/html 8080
4753
# open http://localhost:8080/
4854
```
4955

5056
The first build fetches `doxygen-awesome-css` v2.3.4 (~150 KB) into
51-
`docs/_theme/doxygen-awesome/`. Subsequent builds skip the download.
57+
`docs/_theme/doxygen-awesome/`; later builds skip the download.
58+
59+
`build.sh` does not fail on every Doxygen warning — one stale comment in a
60+
legacy adapter header would then stop the site from building. It fails on a
61+
warning in the **guarded** surface instead: the kernel and native API headers,
62+
the two C headers, `groups.dox` and `examples/native/`. Warnings anywhere else
63+
are printed and counted.
64+
65+
## Editing
66+
67+
- **API reference** — add Doxygen comments (`/** … */`) to declarations in the
68+
public headers; they are extracted automatically.
69+
- **A new narrative page** — put it under `docs/pages/`, give it a
70+
`# Title {#anchor}` first line so other pages can `@ref anchor` it, register
71+
it in the `Doxyfile` `INPUT` list, and add a row to the page index at the
72+
bottom of `pages/index.md`.
73+
- **Citations** — cite the tree with the symbol in backticks immediately
74+
before a path and line number:
75+
76+
```
77+
... one `NativeRunSpec` native_run_spec.hpp:490 names the clock ...
78+
```
5279

53-
## Editing pages
80+
That is an *anchor*. `scripts/check_doc_anchors.py` checks that the cited
81+
line still holds the claimed symbol, and `--fix` re-anchors the unambiguous
82+
ones after a header moves. The full grammar is that script's own docstring.
83+
84+
## The documentation guards
85+
86+
Three checks run over the published pages. They are described in full, with
87+
what each refuses, in [`docs/ci.md`](ci.md).
88+
89+
```bash
90+
python3 scripts/check_doc_anchors.py # every file:line resolves to its symbol
91+
python3 scripts/check_doc_lint.py # no stale epoch, roadmap label or dead link
92+
python3 scripts/check_pine_to_native_coverage.py # every Pine builtin has a migration row
93+
```
5494

55-
- Add Doxygen-style comments (`/** ... */`) to public C ABI declarations
56-
in `include/pineforge/pineforge.h` — auto-extracted into the API
57-
reference.
58-
- Add narrative markdown pages under `docs/pages/`. Register them in
59-
`Doxyfile`'s `INPUT` list. Use `{#anchor}` after the `# Title` so other
60-
pages can `@ref anchor` them.
61-
- The mainpage is `pages/index.md` (declared via `USE_MDFILE_AS_MAINPAGE`).
95+
All three run in `scripts/ci_preflight.py`. The coverage check is binding; the
96+
anchor and lint checks run advisory until the remaining page rewrites land, and
97+
`--strict-docs` makes them binding today.
6298

6399
## Deployment (Cloudflare Pages)
64100

65-
The `.github/workflows/docs.yml` workflow builds and deploys on every
66-
push to `main` and every `v*` tag.
101+
The `.github/workflows/docs.yml` workflow builds and deploys on every push to
102+
`main` and every `v*` tag.
67103

68104
### One-time setup
69105

70-
1. Create a Cloudflare Pages project (any name; default
71-
`pineforge-docs`). Use **Direct Upload** as the connection method —
72-
no Git integration needed; the workflow pushes via Wrangler.
106+
1. Create a Cloudflare Pages project (any name; default `pineforge-docs`). Use
107+
**Direct Upload** as the connection method — no Git integration needed; the
108+
workflow pushes via Wrangler.
73109

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

@@ -79,15 +115,15 @@ push to `main` and every `v*` tag.
79115
| Secret | `CLOUDFLARE_ACCOUNT_ID` | Found in the right sidebar of the Cloudflare dashboard. |
80116
| Variable | `CF_PAGES_PROJECT` | Pages project name. Optional — defaults to `pineforge-docs`. |
81117

82-
3. Push to `main` (or run **Actions → docs → Run workflow**). The site
83-
appears at `https://<project>.pages.dev/`.
118+
3. Push to `main` (or run **Actions → docs → Run workflow**). The site appears
119+
at `https://<project>.pages.dev/`.
84120

85121
### Custom domain
86122

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

90-
If you'd rather host on **GitHub Pages** instead, swap the
126+
If you would rather host on **GitHub Pages**, swap the
91127
`cloudflare/wrangler-action` step for `actions/deploy-pages@v4` plus
92-
`actions/upload-pages-artifact@v3` — the build output (`docs/site/html`)
93-
is identical.
128+
`actions/upload-pages-artifact@v3` — the build output (`docs/site/html`) is
129+
identical.

0 commit comments

Comments
 (0)