diff --git a/CLAUDE.md b/CLAUDE.md
index 813a8e52..3f17f445 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -22,7 +22,7 @@ cd examples/hello && go test ./... # separate workspace module, not co
go install ./cmd/summer # the CLI
go test ./cmd/summer -run TestDocsTree # docs checker
summer docs:build --check # docs checker (identifiers, links, anchors, src= snippets, command names)
-summer docs:sync # refresh src= code copies in docs/ after changing their source
+summer docs:sync # refresh src= code copies in docs/ and module READMEs after changing their source
npm --prefix admin ci
npm --prefix admin run test | test:browser | typecheck | build | dev
diff --git a/README.md b/README.md
index 69881883..194bf2b6 100644
--- a/README.md
+++ b/README.md
@@ -165,7 +165,7 @@ npm --prefix admin run gen:api # regenerate TypeScript types from admin/open
`summer dev` watches an application's sources and rebuilds its binary on change.
-`summer docs:build` renders `docs/` and every module README into a static site under `site/` (use `--out` for another directory, `--check` to validate without writing). Code blocks with a `src=` reference are copies of real source, and `src=` works on top-level code blocks of `docs/` pages only; after changing that source, run `summer docs:sync` to refresh the copies.
+`summer docs:build` renders `docs/` and every module README into a static site under `site/` (use `--out` for another directory, `--check` to validate without writing). Code blocks with a `src=` reference are copies of real source, and `src=` works on top-level code blocks of `docs/` pages and module READMEs; after changing that source, run `summer docs:sync` to refresh the copies.
`summer docs:serve` builds the same site into a temporary directory and previews it at `http://127.0.0.1:8088` (`--addr` to change it), rebuilding when the docs, a module or a `src=` source changes; a failed rebuild prints its problems and keeps serving the last good build. It listens only on a loopback address unless you pass `--allow-remote`. Search needs this server: browsers block the search index over `file://`.
diff --git a/docs/console/utilities.md b/docs/console/utilities.md
index f94871d3..c447558d 100644
--- a/docs/console/utilities.md
+++ b/docs/console/utilities.md
@@ -34,7 +34,7 @@ These docs are Markdown files under `docs/`, plus every module README, built int
| Command | Flags | Purpose |
|---------|-------|---------|
| `summer docs:build` | `--root` (default `.`), `--src`, `--out`, `--base-url`, `--site-url`, `--site-label`, `--check` | Checks every page and writes the site to `site/` (or `--out`): HTML pages, a raw `.md` copy of each page, `llms.txt`, `llms-full.txt` and the search index. With `--check` it only reports problems and writes nothing. |
-| `summer docs:sync` | `--root` (default `.`), `--src` | Rewrites every code block that has a `src=` reference from its source file. |
+| `summer docs:sync` | `--root` (default `.`), `--src` | Rewrites every code block that has a `src=` reference, in docs pages and module READMEs, from its source file. |
| `summer docs:serve` | `--root` (default `.`), `--src`, `--base-url`, `--site-url`, `--site-label`, `--addr` (default `127.0.0.1:8088`), `--allow-remote` | Builds the site into a temporary directory, serves it and rebuilds when a page, a module or a referenced source changes. A failed rebuild prints its problems and keeps serving the last good build. Ctrl+C stops it and exits 0. |
`docs/site.yaml` accepts two optional keys, `site_url` and `site_label`, that add a link back to the main site to every page header. With `site_url: https://acme.example/` the link reads "acme.example". Without `site_label` the label is the URL's host, or Home when `site_url` is a path such as `/`. `site_url` must be an `http://` or `https://` URL with a host, or a path starting with a single `/`. The `--site-url` and `--site-label` flags override the two keys the way `--base-url` overrides `base_url`.
@@ -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, a `src=` code block inside a callout, blockquote or list item (`src=` blocks must be top-level), and a `src=` code block in a module README. 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 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/checks_test.go b/internal/docsite/checks_test.go
index 7ff70c70..81070f76 100644
--- a/internal/docsite/checks_test.go
+++ b/internal/docsite/checks_test.go
@@ -504,6 +504,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.
readme := strings.Join([]string{
"# fixture",
"",
@@ -515,15 +518,42 @@ func TestNestedFenceChecks(t *testing.T) {
"x := 1",
"```",
"",
- "```go src=modules/fixture/fixture.go",
- "package fixture",
+ "```go src=modules/fixture/example_test.go#ExampleHello",
+ "fmt.Println(\"hello\")",
+ "// Output: hello",
+ "```",
+ "",
+ "```go src=modules/fixture/example_test.go#ExampleHello",
+ "stale",
+ "```",
+ "",
+ "- item",
+ "",
+ " ```go src=modules/fixture/example_test.go#ExampleHello",
+ " stale",
+ " ```",
+ "",
+ "> [!NOTE]",
+ "> ```go src=modules/fixture/example_test.go#ExampleHello",
+ "> ```",
+ "",
+ "```text src=modules/fixture/.env",
+ "```",
+ "",
+ "```go src=modules/fixture/example_test.go#ExampleSilent",
"```",
"",
}, "\n")
+ exampleTest := "package fixture\n\nimport \"fmt\"\n\n" +
+ "func ExampleHello() {\n\tfmt.Println(\"hello\")\n\t// Output: hello\n}\n\n" +
+ "func ExampleSilent() {\n\tfmt.Println(\"quiet\")\n}\n"
+ const hello = "modules/fixture/example_test.go#ExampleHello"
assertProblems(t, checkFixture(t, fixtureCommands, map[string]string{
- "docs/index.md": page("Acme docs", "index", 0, "Text.\n"),
- "docs/setup/start.md": page("Start", "setup", 10, body),
- "modules/fixture/README.md": readme,
+ "go.mod": "module example.com/acme\n\ngo 1.27\n",
+ "docs/index.md": page("Acme docs", "index", 0, "Text.\n"),
+ "docs/setup/start.md": page("Start", "setup", 10, body),
+ "modules/fixture/README.md": readme,
+ "modules/fixture/example_test.go": exampleTest,
}), []string{
"docs/setup/start.md:10: snippet: go code block has no src= reference",
"docs/setup/start.md:16: snippet: go code block has no src= reference",
@@ -531,7 +561,11 @@ 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:11: snippet: modules/fixture/fixture.go: " + readmeSrcMessage,
+ "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,
+ "modules/fixture/README.md:30: snippet: modules/fixture/.env: path names a dotfile or .env file",
+ "modules/fixture/README.md:33: snippet: modules/fixture/example_test.go#ExampleSilent: ExampleSilent has no // Output: comment, so go test compiles it but never runs it",
})
}
diff --git a/internal/docsite/render.go b/internal/docsite/render.go
index 40962bc7..5c208a0f 100644
--- a/internal/docsite/render.go
+++ b/internal/docsite/render.go
@@ -59,10 +59,11 @@ func (fenceAnnotator) Transform(doc *ast.Document, reader text.Reader, pc parser
if !entering || !ok || fc.Info == nil {
return ast.WalkContinue, nil
}
- // Captions only on the fences checkSnippets compares: top-level
- // src= fences of docs/ pages. A nested or module README fence is
- // not verified, so it must not claim a source.
- verified := pctx != nil && pctx.page != nil && pctx.page.Module == "" &&
+ // Captions only on the fences checkSnippets compares: the
+ // top-level src= fences of every page, docs/ pages and module
+ // READMEs alike. A nested fence is refused, not verified, so it
+ // must not claim a source.
+ verified := pctx != nil && pctx.page != nil &&
fc.Parent() != nil && fc.Parent().Kind() == ast.KindDocument
if !verified {
return ast.WalkContinue, nil
diff --git a/internal/docsite/render_test.go b/internal/docsite/render_test.go
index 10aa6481..ae1540d5 100644
--- a/internal/docsite/render_test.go
+++ b/internal/docsite/render_test.go
@@ -71,7 +71,7 @@ func renderHTML(t *testing.T, s *site, p *Page) renderedPage {
return r
}
-func TestFenceCaptionsOnlyVerified(t *testing.T) {
+func TestFenceCaptionsTopLevelSrc(t *testing.T) {
guide := page("Start", "setup", 10, strings.Join([]string{
"```go src=pkg/lib.go#Greeting",
"func Greeting() {}",
@@ -83,7 +83,8 @@ func TestFenceCaptionsOnlyVerified(t *testing.T) {
"> ```",
"",
}, "\n"))
- readme := "# alpha\n\nAlpha does one thing.\n\n```go src=modules/alpha/alpha.go\npackage alpha\n```\n"
+ readme := "# alpha\n\nAlpha does one thing.\n\n```go src=modules/alpha/alpha.go\npackage alpha\n```\n\n" +
+ "> [!TIP]\n> ```go src=modules/alpha/alpha.go#Nested\n> package alpha\n> ```\n"
s, pages := renderFixture(t, map[string]string{
"docs/setup/start.md": guide,
"modules/alpha/README.md": readme,
@@ -95,9 +96,14 @@ func TestFenceCaptionsOnlyVerified(t *testing.T) {
if !strings.Contains(guideHTML, "pkg/lib.go#Greeting") {
t.Fatalf("guide caption missing the top-level reference\n%s", guideHTML)
}
+ // A module README captions its top-level src= fence like a docs/
+ // page; the fence nested in the callout gets none.
readmeHTML := string(renderHTML(t, s, pages["api/alpha"]).html)
- if strings.Contains(readmeHTML, "") {
- t.Fatalf("module README has a caption\n%s", readmeHTML)
+ if got := strings.Count(readmeHTML, ""); got != 1 {
+ t.Fatalf("module README figcaptions = %d, want 1\n%s", got, readmeHTML)
+ }
+ if !strings.Contains(readmeHTML, "modules/alpha/alpha.go") {
+ t.Fatalf("module README caption missing the top-level reference\n%s", readmeHTML)
}
}
diff --git a/internal/docsite/snippet.go b/internal/docsite/snippet.go
index a3183692..15dd20c3 100644
--- a/internal/docsite/snippet.go
+++ b/internal/docsite/snippet.go
@@ -530,14 +530,11 @@ type drift struct {
// its container marker, so the fence is refused instead of extracted.
const nestedSrcMessage = "src= code block must be a top-level block of the page, not inside a callout, blockquote or list item"
-// readmeSrcMessage is the problem for a src= fence in a module README.
-// Those fences are rendered as written and never compared, so a src=
-// there would claim a check that does not run.
-const readmeSrcMessage = "module README code blocks are rendered as written; src= is verified only in docs/ pages"
-
-// checkFences verifies every src= fence in fences. lines are the body
-// lines the fences index into. lineBase is the 1-based file line of
-// lines[0]; file is the display path for problems.
+// checkFences verifies every src= fence in fences, on a docs/ page or a
+// module README alike: a top-level fence is extracted and compared with
+// its source, a nested one is refused. lines are the body lines the
+// fences index into. lineBase is the 1-based file line of lines[0]; file
+// is the display path for problems.
func checkFences(root, file string, lines []string, lineBase int, fences []mdFence) ([]drift, []Problem, error) {
var drifts []drift
var problems []Problem
@@ -596,9 +593,10 @@ func unindent(l string, n int) string {
return l[i:]
}
-// checkSnippets verifies the src= fences of every page. A docs/ page is
-// compared with its source. A module README is rendered as written, so
-// any src= fence there is refused instead of checked.
+// checkSnippets verifies the src= fences of every page, docs/ pages and
+// module READMEs alike: each top-level src= fence is compared with its
+// source. A README page keeps its file's line indices (BodyLine 1), so
+// problems cite the README's own lines.
func (s *site) checkSnippets(docs []parsedDoc) ([]Problem, error) {
var problems []Problem
for _, d := range docs {
@@ -609,17 +607,6 @@ func (s *site) checkSnippets(docs []parsedDoc) ([]Problem, error) {
if err != nil {
return nil, err
}
- if d.page.Module != "" {
- for _, f := range fences {
- ref, ok := ParseSrc(f.info)
- if !ok {
- continue
- }
- problems = append(problems, Problem{File: d.file, Line: d.line + f.line, Rule: "snippet",
- Message: ref.String() + ": " + readmeSrcMessage})
- }
- continue
- }
_, ps, err := checkFences(s.opts.Root, d.file, strings.Split(string(d.body), "\n"), d.line, fences)
if err != nil {
return nil, err
@@ -629,9 +616,10 @@ func (s *site) checkSnippets(docs []parsedDoc) ([]Problem, error) {
return problems, nil
}
-// Sync rewrites every drifted src= fence body under Src from its source,
-// preserving everything else byte for byte. When a reference is missing or
-// breaks a rule, it returns the problems and writes nothing.
+// Sync rewrites every drifted src= fence body from its source, in the
+// pages under Src and in every modules//README.md under Root,
+// preserving everything else byte for byte. When a reference anywhere is
+// missing or breaks a rule, it returns the problems and writes nothing.
func Sync(opts Options) (SyncResult, []Problem, error) {
opts, err := opts.normalize()
if err != nil {
@@ -642,6 +630,20 @@ func Sync(opts Options) (SyncResult, []Problem, error) {
if err != nil {
return SyncResult{}, nil, err
}
+ // Module READMEs come from Root, as load ingests them. A module
+ // without a README is skipped here; load reports it.
+ names, err := moduleNames(opts.Root)
+ if err != nil {
+ return SyncResult{}, nil, err
+ }
+ for _, name := range names {
+ readme := filepath.Join(opts.Root, "modules", name, "README.md")
+ if _, err := os.Stat(readme); err == nil {
+ files = append(files, readme)
+ } else if !errors.Is(err, fs.ErrNotExist) {
+ return SyncResult{}, nil, fmt.Errorf("docs:sync: %w", err)
+ }
+ }
type rewrite struct {
path string
mode fs.FileMode
diff --git a/internal/docsite/snippet_test.go b/internal/docsite/snippet_test.go
index 471ef14e..edef382b 100644
--- a/internal/docsite/snippet_test.go
+++ b/internal/docsite/snippet_test.go
@@ -478,3 +478,94 @@ func TestSyncParsedFences(t *testing.T) {
t.Fatal(err)
}
}
+
+// treeContents reads every file under root, keyed by path.
+func treeContents(t *testing.T, root string) map[string]string {
+ t.Helper()
+ files := map[string]string{}
+ err := filepath.WalkDir(root, func(p string, d os.DirEntry, err error) error {
+ if err != nil || d.IsDir() {
+ return err
+ }
+ b, err := os.ReadFile(p)
+ if err != nil {
+ return err
+ }
+ files[p] = string(b)
+ return nil
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+ return files
+}
+
+func TestSyncModuleReadme(t *testing.T) {
+ const alphaTest = "package alpha\n\nimport \"fmt\"\n\n" +
+ "func ExampleHello() {\n\tfmt.Println(\"hello\")\n\t// Output: hello\n}\n"
+ readme := strings.Join([]string{
+ "# alpha",
+ "",
+ "Alpha does one thing.",
+ "",
+ "`import \"example.com/acme/modules/alpha\"`",
+ "",
+ "## Usage",
+ "",
+ "Prose before.",
+ "",
+ "```go src=modules/alpha/alpha_test.go#ExampleHello",
+ "stale",
+ "```",
+ "",
+ "Prose `alpha` after.",
+ "",
+ "```sh",
+ "summer docs:build",
+ "```",
+ "",
+ }, "\n")
+ tree := map[string]string{
+ "modules/alpha/alpha.go": "package alpha\n",
+ "modules/alpha/alpha_test.go": alphaTest,
+ "modules/alpha/README.md": readme,
+ // A module directory without a README is skipped; load reports it.
+ "modules/beta/beta.go": "package beta\n",
+ }
+ root := snippetTree(t, tree)
+ path := filepath.Join(root, "modules/alpha/README.md")
+ res, problems, err := Sync(Options{Root: root})
+ if err != nil || len(problems) > 0 || res != (SyncResult{Snippets: 1, Files: 1}) {
+ t.Fatalf("Sync = %+v %q %v", res, problemLines(problems), err)
+ }
+ got, err := os.ReadFile(path)
+ if err != nil {
+ t.Fatal(err)
+ }
+ want := strings.Replace(readme, "stale\n", "fmt.Println(\"hello\")\n// Output: hello\n", 1)
+ if string(got) != want {
+ t.Fatalf("synced README =\n%s\nwant\n%s", got, want)
+ }
+ if res, problems, err := Sync(Options{Root: root}); err != nil || len(problems) > 0 || res != (SyncResult{}) {
+ t.Fatalf("second Sync = %+v %q %v", res, problemLines(problems), err)
+ }
+
+ // A refused README fence blocks every write, docs/ pages included.
+ tree["modules/alpha/README.md"] = readme + "\n```text src=modules/alpha/.env\n```\n"
+ tree["docs/setup/start.md"] = page("Start", "setup", 10, "```go src=pkg/lib.go#Greeting\nstale\n```\n")
+ root = snippetTree(t, tree)
+ before := treeContents(t, root)
+ res, problems, err = Sync(Options{Root: root})
+ if err != nil || res != (SyncResult{}) {
+ t.Fatalf("Sync with a refused README fence = %+v, %v", res, err)
+ }
+ assertProblems(t, problemLines(problems), []string{
+ "modules/alpha/README.md:21: snippet: modules/alpha/.env: path names a dotfile or .env file",
+ })
+ after := treeContents(t, root)
+ for p, b := range before {
+ if after[p] != b {
+ t.Errorf("Sync changed %s although a README reference was refused", p)
+ }
+ }
+}
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 9f374b44..84bd6456 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
@@ -19,6 +19,6 @@ go test ./modules/demo
```
```go src=modules/demo/example_test.go#ExampleHello
-fmt.Println(demo.Hello("blog"))
-// Output: Hello, blog
+fmt.Println(demo.Hello("world"))
+// Output: Hello, world
```
diff --git a/internal/docsite/testdata/violations/snippet-readme-src/want.txt b/internal/docsite/testdata/violations/snippet-readme-src/want.txt
index 715f4099..0c17c8dc 100644
--- a/internal/docsite/testdata/violations/snippet-readme-src/want.txt
+++ b/internal/docsite/testdata/violations/snippet-readme-src/want.txt
@@ -1,3 +1,3 @@
rule: snippet
file: modules/demo/README.md
-message: modules/demo/example_test.go#ExampleHello: module README code blocks are rendered as written
+message: body differs from modules/demo/example_test.go#ExampleHello (run: summer docs:sync)