feat(docsite): require src= on Go code blocks of module READMEs (quick-261118-qsd)

This commit is contained in:
Jakub Zych
2026-11-18 20:18:38 +01:00
parent 1e56d750ef
commit 8c03cc3621
11 changed files with 43 additions and 40 deletions

View File

@@ -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. - 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. - 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. - 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 ## MSD workflow

View File

@@ -45,6 +45,6 @@ summer docs:sync
summer docs:serve 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. `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.

View File

@@ -12,8 +12,8 @@ import (
var calloutTypes = []string{"NOTE", "TIP", "WARNING"} var calloutTypes = []string{"NOTE", "TIP", "WARNING"}
// checkPolicy enforces the page content rules: // checkPolicy enforces the page content rules:
// - every Go-lexer fence in a docs/ page carries src=, at any depth // - every Go-lexer fence of every page, docs/ pages and module READMEs
// (module READMEs are rendered as written, D-18); // alike, carries src=, at any depth;
// - callouts are NOTE, TIP or WARNING; // - callouts are NOTE, TIP or WARNING;
// - docs/ headings are plain ASCII text without links or code spans. // - docs/ headings are plain ASCII text without links or code spans.
func (s *site) checkPolicy(docs []parsedDoc) ([]Problem, error) { func (s *site) checkPolicy(docs []parsedDoc) ([]Problem, error) {
@@ -22,21 +22,18 @@ func (s *site) checkPolicy(docs []parsedDoc) ([]Problem, error) {
if d.page == nil { if d.page == nil {
continue continue
} }
guide := d.page.Module == "" fences, err := collectFences(d.doc, d.body)
if guide { if err != nil {
fences, err := collectFences(d.doc, d.body) return nil, err
if err != nil { }
return nil, err for _, f := range fences {
} if _, hasSrc := ParseSrc(f.info); goLang(f.lang) && !hasSrc {
for _, f := range fences { problems = append(problems, Problem{File: d.file, Line: d.line + f.line, Rule: "snippet",
if _, hasSrc := ParseSrc(f.info); goLang(f.lang) && !hasSrc { Message: f.lang + " code block has no src= reference"})
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)...) problems = append(problems, calloutProblems(d)...)
if guide { if d.page.Module == "" {
problems = append(problems, headingProblems(d)...) problems = append(problems, headingProblems(d)...)
} }
} }

View File

@@ -254,7 +254,7 @@ func TestForbiddenChecker(t *testing.T) {
} }
func TestFencePolicy(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" + 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" "```yaml\nkey: value\n```\n\n```md\n> [!DANGER]\n```\n"
assertProblems(t, checkFixture(t, fixtureCommands, map[string]string{ 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" 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{ assertProblems(t, checkFixture(t, fixtureCommands, map[string]string{
"docs/index.md": page("Acme docs", "index", 0, bad), "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{ }), []string{
"docs/index.md:29: snippet: go code block has no src= reference", "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)", "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: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", "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: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") }, "\n")
// A module README's src= fences are checked like a docs/ page's: a // A module README's fences are checked like a docs/ page's: a Go
// matching body passes, drift, nesting and refused targets are // fence without src= is refused, a matching src= body passes, drift,
// reported at the README's own lines. // nesting and refused targets are reported at the README's own lines.
readme := strings.Join([]string{ readme := strings.Join([]string{
"# fixture", "# 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: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:34: command: "bogus:nested" is not a summer or application command`,
"docs/setup/start.md:37: snippet: config/app.yaml: " + nestedSrcMessage, "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:16: snippet: body differs from " + hello + " (run: summer docs:sync)",
"modules/fixture/README.md:22: snippet: " + hello + ": " + nestedSrcMessage, "modules/fixture/README.md:22: snippet: " + hello + ": " + nestedSrcMessage,
"modules/fixture/README.md:27: snippet: " + hello + ": " + nestedSrcMessage, "modules/fixture/README.md:27: snippet: " + hello + ": " + nestedSrcMessage,

View File

@@ -2,9 +2,9 @@
Demo greets people by name. 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 ## Usage

View File

@@ -2,9 +2,9 @@
Demo greets people by name. 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 ## Usage

View File

@@ -2,9 +2,9 @@
Demo greets people by name. 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 ## Usage

View File

@@ -2,9 +2,9 @@
Demo greets people by name. 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 ## Usage

View File

@@ -2,9 +2,9 @@
Demo greets people by name. 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 ## Usage

View File

@@ -2,9 +2,9 @@
Demo greets people by name. 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 ## Usage

View File

@@ -16,7 +16,7 @@ import (
) )
// themeTree is a two-section fixture: the index (two H2 headings, a // 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 { func themeTree(t *testing.T) string {
t.Helper() t.Helper()
return writeTree(t, map[string]string{ 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/start.md": page("Start", "setup", 10, "## Only heading\n\nText.\n"),
"docs/setup/second.md": page("Second", "setup", 20, "Text.\n"), "docs/setup/second.md": page("Second", "setup", 20, "Text.\n"),
"modules/alpha/alpha.go": "package alpha\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" + "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",
}) })
} }