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

@@ -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)...)
}
}

View File

@@ -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,

View File

@@ -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

View File

@@ -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

View File

@@ -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

View File

@@ -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

View File

@@ -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

View File

@@ -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

View File

@@ -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",
})
}