You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 16f3652
Browse filesBrowse the repository at this point in the historyBrowse files
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)
`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
+
38
44
## Build locally
39
45
40
46
```bash
41
47
# 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
44
50
45
51
bash docs/build.sh
46
52
python3 -m http.server -d docs/site/html 8080
47
53
# open http://localhost:8080/
48
54
```
49
55
50
56
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
+
```
52
79
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
+
```
54
94
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.
62
98
63
99
## Deployment (Cloudflare Pages)
64
100
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.
67
103
68
104
### One-time setup
69
105
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.
73
109
74
110
2. In the repo, add these secrets and (optionally) a variable:
75
111
@@ -79,15 +115,15 @@ push to `main` and every `v*` tag.
79
115
| Secret |`CLOUDFLARE_ACCOUNT_ID`| Found in the right sidebar of the Cloudflare dashboard. |
0 commit comments