From 8c03cc362190f72d8ba24e8fcc60bc09a5f26cc7 Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Wed, 18 Nov 2026 20:18:38 +0100 Subject: [PATCH] feat(docsite): require src= on Go code blocks of module READMEs (quick-261118-qsd) --- CLAUDE.md | 1 + docs/console/utilities.md | 2 +- internal/docsite/check_policy.go | 25 ++++++++----------- internal/docsite/checks_test.go | 12 +++++---- .../testdata/clean/modules/demo/README.md | 6 ++--- .../modules/demo/README.md | 6 ++--- .../command-in-readme/modules/demo/README.md | 6 ++--- .../modules/demo/README.md | 6 ++--- .../link-module-readme/modules/demo/README.md | 6 ++--- .../snippet-readme-src/modules/demo/README.md | 6 ++--- internal/docsite/theme_test.go | 7 ++++-- 11 files changed, 43 insertions(+), 40 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 3f17f445..114473c6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -58,6 +58,7 @@ Framework code never names a consuming application (READMEs, docs, examples use - A change to a module's exported API, config keys, CLI commands or dependencies updates that module's `README.md` and the affected `docs/` pages in the same commit. - Module README structure: H1 name, one-sentence summary, import line, `**Name:**` mnemonic, then Overview, Features, Usage, API reference, optional Configuration and CLI commands, Dependencies, Testing. The root table's purpose text reuses the summary sentence. - Every identifier in a README or docs page must exist in the package (the docs checker enforces it). Config keys are not checked automatically; review them by hand. +- Go code blocks in `docs/` pages and module READMEs are `src=` references into compiled test code (usually the module's `example_test.go`): an Example with `// Output:`, a `docs:start`/`docs:end` region, or a declaration a test runs. `summer docs:build --check` compares them with their source, and `summer docs:sync` refreshes them after the source changes. ## MSD workflow diff --git a/docs/console/utilities.md b/docs/console/utilities.md index c447558d..518bc248 100644 --- a/docs/console/utilities.md +++ b/docs/console/utilities.md @@ -45,6 +45,6 @@ summer docs:sync summer docs:serve ``` -`summer help docs:build` and `summer help docs:sync` show examples. `docs:build` fails, and writes nothing, when a page names an identifier that does not exist, links to a missing page or anchor, shows a command that neither `summer` nor an application binary has, or has a `src=` code block that differs from its source. It also fails on a Go code block (including `golang`) without a `src=` reference and on a `src=` code block inside a callout, blockquote or list item; `src=` works on top-level code blocks of docs pages and module READMEs. A `src=` target must be code `go test ./...` compiles and runs, that is a file in the default build, inside a `Test` function or an `Example` with an `// Output:` comment, or a function one of them calls. After you change code that a page shows, run `summer docs:sync` to refresh the copies. +`summer help docs:build` and `summer help docs:sync` show examples. `docs:build` fails, and writes nothing, when a page names an identifier that does not exist, links to a missing page or anchor, shows a command that neither `summer` nor an application binary has, or has a `src=` code block that differs from its source. It also fails on a Go code block (including `golang`) without a `src=` reference, in docs pages and module READMEs alike, and on a `src=` code block inside a callout, blockquote or list item; `src=` works on top-level code blocks of docs pages and module READMEs. A `src=` target must be code `go test ./...` compiles and runs, that is a file in the default build, inside a `Test` function or an `Example` with an `// Output:` comment, or a function one of them calls. After you change code that a page shows, run `summer docs:sync` to refresh the copies. `docs:serve` listens only on a loopback address unless you pass `--allow-remote`. Use it to preview search, which browsers block when you open the built files directly from disk. diff --git a/internal/docsite/check_policy.go b/internal/docsite/check_policy.go index dc65b837..a8dfd590 100644 --- a/internal/docsite/check_policy.go +++ b/internal/docsite/check_policy.go @@ -12,8 +12,8 @@ import ( var calloutTypes = []string{"NOTE", "TIP", "WARNING"} // checkPolicy enforces the page content rules: -// - every Go-lexer fence in a docs/ page carries src=, at any depth -// (module READMEs are rendered as written, D-18); +// - every Go-lexer fence of every page, docs/ pages and module READMEs +// alike, carries src=, at any depth; // - callouts are NOTE, TIP or WARNING; // - docs/ headings are plain ASCII text without links or code spans. func (s *site) checkPolicy(docs []parsedDoc) ([]Problem, error) { @@ -22,21 +22,18 @@ func (s *site) checkPolicy(docs []parsedDoc) ([]Problem, error) { if d.page == nil { continue } - guide := d.page.Module == "" - if guide { - fences, err := collectFences(d.doc, d.body) - if err != nil { - return nil, err - } - for _, f := range fences { - if _, hasSrc := ParseSrc(f.info); goLang(f.lang) && !hasSrc { - problems = append(problems, Problem{File: d.file, Line: d.line + f.line, Rule: "snippet", - Message: f.lang + " code block has no src= reference"}) - } + fences, err := collectFences(d.doc, d.body) + if err != nil { + return nil, err + } + for _, f := range fences { + if _, hasSrc := ParseSrc(f.info); goLang(f.lang) && !hasSrc { + problems = append(problems, Problem{File: d.file, Line: d.line + f.line, Rule: "snippet", + Message: f.lang + " code block has no src= reference"}) } } problems = append(problems, calloutProblems(d)...) - if guide { + if d.page.Module == "" { problems = append(problems, headingProblems(d)...) } } diff --git a/internal/docsite/checks_test.go b/internal/docsite/checks_test.go index 81070f76..f5180261 100644 --- a/internal/docsite/checks_test.go +++ b/internal/docsite/checks_test.go @@ -254,7 +254,7 @@ func TestForbiddenChecker(t *testing.T) { } func TestFencePolicy(t *testing.T) { - readme := "# fixture\n\nFixture does one thing.\n\n## Usage of `fixture`\n\n```go\nfixture.Run()\n```\n\n> [!TIP]\n> Fine.\n" + readme := "# fixture\n\nFixture does one thing.\n\n## Usage of `fixture`\n\n```text\nfixture.Run()\n```\n\n> [!TIP]\n> Fine.\n" good := "## Plain heading\n\n> [!NOTE]\n> A note.\n\n> [!WARNING]\n> Careful.\n\n```text\nplain\n```\n\n" + "```yaml\nkey: value\n```\n\n```md\n> [!DANGER]\n```\n" assertProblems(t, checkFixture(t, fixtureCommands, map[string]string{ @@ -265,7 +265,7 @@ func TestFencePolicy(t *testing.T) { bad := good + "\n```go\nfmt.Println()\n```\n\n> [!DANGER]\n> Boom.\n\n## Use `fixture`\n\n## Zażółć\n\n## See [start](setup/start.md)\n" assertProblems(t, checkFixture(t, fixtureCommands, map[string]string{ "docs/index.md": page("Acme docs", "index", 0, bad), - "modules/fixture/README.md": readme + "\n> [!CAUTION]\n> No.\n", + "modules/fixture/README.md": readme + "\n> [!CAUTION]\n> No.\n\n```go\nfixture.Run()\n```\n", }), []string{ "docs/index.md:29: snippet: go code block has no src= reference", "docs/index.md:33: callout: unknown type DANGER (use NOTE, TIP or WARNING)", @@ -273,6 +273,7 @@ func TestFencePolicy(t *testing.T) { "docs/index.md:38: heading: headings must be plain ASCII text without links or code", "docs/index.md:40: heading: headings must be plain ASCII text without links or code", "modules/fixture/README.md:14: callout: unknown type CAUTION (use NOTE, TIP or WARNING)", + "modules/fixture/README.md:17: snippet: go code block has no src= reference", }) } @@ -504,9 +505,9 @@ func TestNestedFenceChecks(t *testing.T) { "> ```", "", }, "\n") - // A module README's src= fences are checked like a docs/ page's: a - // matching body passes, drift, nesting and refused targets are - // reported at the README's own lines. + // A module README's fences are checked like a docs/ page's: a Go + // fence without src= is refused, a matching src= body passes, drift, + // nesting and refused targets are reported at the README's own lines. readme := strings.Join([]string{ "# fixture", "", @@ -561,6 +562,7 @@ func TestNestedFenceChecks(t *testing.T) { "docs/setup/start.md:24: snippet: main.go code block has no src= reference", `docs/setup/start.md:34: command: "bogus:nested" is not a summer or application command`, "docs/setup/start.md:37: snippet: config/app.yaml: " + nestedSrcMessage, + "modules/fixture/README.md:7: snippet: go code block has no src= reference", "modules/fixture/README.md:16: snippet: body differs from " + hello + " (run: summer docs:sync)", "modules/fixture/README.md:22: snippet: " + hello + ": " + nestedSrcMessage, "modules/fixture/README.md:27: snippet: " + hello + ": " + nestedSrcMessage, diff --git a/internal/docsite/testdata/clean/modules/demo/README.md b/internal/docsite/testdata/clean/modules/demo/README.md index 410dfc4a..5d25294c 100644 --- a/internal/docsite/testdata/clean/modules/demo/README.md +++ b/internal/docsite/testdata/clean/modules/demo/README.md @@ -2,9 +2,9 @@ Demo greets people by name. -```go -import "example.com/docfixture/modules/demo" -``` +`import "example.com/docfixture/modules/demo"` + +**Name:** A demo says hello, so the fixture has something to greet with. ## Usage diff --git a/internal/docsite/testdata/violations/callout-unknown-readme/modules/demo/README.md b/internal/docsite/testdata/violations/callout-unknown-readme/modules/demo/README.md index 350f6dcc..79a5d4da 100644 --- a/internal/docsite/testdata/violations/callout-unknown-readme/modules/demo/README.md +++ b/internal/docsite/testdata/violations/callout-unknown-readme/modules/demo/README.md @@ -2,9 +2,9 @@ Demo greets people by name. -```go -import "example.com/docfixture/modules/demo" -``` +`import "example.com/docfixture/modules/demo"` + +**Name:** A demo says hello, so the fixture has something to greet with. ## Usage diff --git a/internal/docsite/testdata/violations/command-in-readme/modules/demo/README.md b/internal/docsite/testdata/violations/command-in-readme/modules/demo/README.md index 19c1c092..3364f5bc 100644 --- a/internal/docsite/testdata/violations/command-in-readme/modules/demo/README.md +++ b/internal/docsite/testdata/violations/command-in-readme/modules/demo/README.md @@ -2,9 +2,9 @@ Demo greets people by name. -```go -import "example.com/docfixture/modules/demo" -``` +`import "example.com/docfixture/modules/demo"` + +**Name:** A demo says hello, so the fixture has something to greet with. ## Usage diff --git a/internal/docsite/testdata/violations/identifier-module-readme/modules/demo/README.md b/internal/docsite/testdata/violations/identifier-module-readme/modules/demo/README.md index d859e134..99cf5f1f 100644 --- a/internal/docsite/testdata/violations/identifier-module-readme/modules/demo/README.md +++ b/internal/docsite/testdata/violations/identifier-module-readme/modules/demo/README.md @@ -2,9 +2,9 @@ Demo greets people by name. -```go -import "example.com/docfixture/modules/demo" -``` +`import "example.com/docfixture/modules/demo"` + +**Name:** A demo says hello, so the fixture has something to greet with. ## Usage diff --git a/internal/docsite/testdata/violations/link-module-readme/modules/demo/README.md b/internal/docsite/testdata/violations/link-module-readme/modules/demo/README.md index db96156b..6b26a8ca 100644 --- a/internal/docsite/testdata/violations/link-module-readme/modules/demo/README.md +++ b/internal/docsite/testdata/violations/link-module-readme/modules/demo/README.md @@ -2,9 +2,9 @@ Demo greets people by name. -```go -import "example.com/docfixture/modules/demo" -``` +`import "example.com/docfixture/modules/demo"` + +**Name:** A demo says hello, so the fixture has something to greet with. ## Usage diff --git a/internal/docsite/testdata/violations/snippet-readme-src/modules/demo/README.md b/internal/docsite/testdata/violations/snippet-readme-src/modules/demo/README.md index 84bd6456..d0c96de2 100644 --- a/internal/docsite/testdata/violations/snippet-readme-src/modules/demo/README.md +++ b/internal/docsite/testdata/violations/snippet-readme-src/modules/demo/README.md @@ -2,9 +2,9 @@ Demo greets people by name. -```go -import "example.com/docfixture/modules/demo" -``` +`import "example.com/docfixture/modules/demo"` + +**Name:** A demo says hello, so the fixture has something to greet with. ## Usage diff --git a/internal/docsite/theme_test.go b/internal/docsite/theme_test.go index daded7ad..52639ae2 100644 --- a/internal/docsite/theme_test.go +++ b/internal/docsite/theme_test.go @@ -16,7 +16,7 @@ import ( ) // themeTree is a two-section fixture: the index (two H2 headings, a -// callout), two setup pages and one API page with a Go fence. +// callout), two setup pages and one API page with a src= Go fence. func themeTree(t *testing.T) string { t.Helper() return writeTree(t, map[string]string{ @@ -27,8 +27,11 @@ func themeTree(t *testing.T) string { "docs/setup/start.md": page("Start", "setup", 10, "## Only heading\n\nText.\n"), "docs/setup/second.md": page("Second", "setup", 20, "Text.\n"), "modules/alpha/alpha.go": "package alpha\n", + "modules/alpha/alpha_test.go": "package alpha\n\nimport \"testing\"\n\n" + + "func TestName(t *testing.T) {\n\tif name() != \"x\" {\n\t\tt.Fatal(name())\n\t}\n}\n\n" + + "func name() string {\n\treturn \"x\" // done\n}\n", "modules/alpha/README.md": "# alpha\n\nAlpha does one thing well.\n\n## Usage\n\n" + - "```go\nfunc main() {\n\treturn \"x\" // done\n}\n```\n\n```yaml\nkey: true\n```\n", + "```go src=modules/alpha/alpha_test.go#name\nfunc name() string {\n\treturn \"x\" // done\n}\n```\n\n```yaml\nkey: true\n```\n", }) }