feat(docsite): require src= on Go code blocks of module READMEs (quick-261118-qsd)
This commit is contained in:
@@ -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
|
||||||
|
|
||||||
|
|||||||
@@ -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.
|
||||||
|
|||||||
@@ -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)...)
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -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,
|
||||||
|
|||||||
@@ -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
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
||||||
|
|
||||||
|
|||||||
@@ -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",
|
||||||
})
|
})
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user