docs(breakwater): compile README Go examples via src= (quick-261118-qsd)

- the Usage fence becomes two src= references to ExampleRender and
  ExamplePurify, filled by summer docs:sync
- the Phase 11.1 SC4 acceptance scan now allows top-level src= fences
  in module READMEs (nested ones are still refused) and expects the
  api/<name> pages to caption them like docs/ pages
This commit is contained in:
Jakub Zych
2026-11-18 19:30:29 +01:00
parent 721830c502
commit 48527e4206
2 changed files with 19 additions and 18 deletions

View File

@@ -243,7 +243,8 @@ func TestPhase11_1Acceptance(t *testing.T) {
}
}
// The acceptance scanner is independent of docsite: a src= fence
// inside a blockquote or list is nested, and a module README has none.
// inside a blockquote or list is nested, in a docs/ page and a
// module README alike.
err := filepath.WalkDir(filepath.Join(repoRoot, "docs"), func(p string, d fs.DirEntry, err error) error {
if err != nil {
return err
@@ -274,8 +275,8 @@ func TestPhase11_1Acceptance(t *testing.T) {
}
rel, _ := filepath.Rel(repoRoot, p)
for _, f := range scanDocFences(filepath.ToSlash(rel), readFile(t, p)) {
if f.src != "" {
t.Errorf("%s:%d: module README has a src= fence", f.file, f.line)
if f.src != "" && f.nested {
t.Errorf("%s:%d: src= fence is nested (%s)", f.file, f.line, f.src)
}
}
return nil
@@ -283,10 +284,9 @@ func TestPhase11_1Acceptance(t *testing.T) {
if err != nil {
t.Fatal(err)
}
// Every page, module README API pages included, captions exactly
// its top-level src= fences.
for _, p := range pages {
if p.Module != "" {
continue
}
n := 0
for _, f := range pageFences(t, p.Source) {
if f.src != "" && !f.nested {
@@ -298,15 +298,6 @@ func TestPhase11_1Acceptance(t *testing.T) {
t.Errorf("%s has %d figcaptions, want %d top-level src= fences", p.URL, got, n)
}
}
api, err := filepath.Glob(filepath.Join(out, "api", "*.html"))
if err != nil {
t.Fatal(err)
}
for _, p := range api {
if strings.Contains(readFile(t, p), "<figcaption>") {
t.Errorf("%s has a figcaption", p)
}
}
})
// SC5: the concept map and the acme/blog walkthrough exist, and the