Files
coder/scripts/docgenenv/sources_test.go
T
Nick Vigilante d187dea338 docs: end every page description with a period and lint for it (#30863)
## Summary

Page descriptions in the docs were inconsistent about ending with a
period. This makes every page description end with one and adds a lint
so it stays that way.

A page description can come from three places, and the docs site reads
front matter first and falls back to the manifest:

- the hand-written YAML sidebar sources under `docs/manifest/`
(including `children_from` overlays),
- the generated fragments (`docs/manifest/generated/cli.json`,
`rest-api.json`), compiled into `docs/manifest.json`,
- a page's own front matter (today only the generated CLI and API
reference pages carry one).

The check covers all three. For the CLI, the description comes from each
command's `Short`, which stays unpunctuated by CLI-help convention, so
`clidocgen` adds the period when it writes the docs description instead
of changing 120 `Short` strings and the CLI golden files.

## What the lint checks

`make lint/docs-manifest` (`docsmanifestgen check`, already part of
`make lint` in CI) now fails when a non-empty description doesn't end
with `.`. No description in the tree ends with `?` or `!`, so the rule
allows only a period. Errors name the source file, the sidebar
breadcrumb, and the description, for example:

```
install/plan/sizing.yml: Install > Plan your deployment > Coder Validated Architecture > Up to 1,000 users: description must end with a period: "Hardware specifications and architecture guidance for Coder deployments that support up to 1,000 users"
generated/api.json: General: description must end with a period: "General endpoints"
reference/cli/ping.md: Reference > Command Line > `ping`: front matter description must end with a period: "Ping a workspace"
```

The style guide's page-description rule now lists the requirement and
cites the checker, and `styleclaims` recognises
`scripts/docsmanifestgen` so the coverage table counts it as
tool-checked.

## Count of descriptions fixed

147 descriptions in `docs/manifest.json`:

- 27 hand-written descriptions in 15 sidebar source files,
- 120 generated CLI descriptions, which also update the front matter of
120 CLI reference pages.

The REST API descriptions already ended with a period. No description is
otherwise reworded.

## Testing

- New table cases in `scripts/docgenenv` (section route, child route,
overlay, generated fragment, front matter, and a `?` ending) and
`scripts/clidocgen`, written first and failing before the change.
- `docsmanifestgen check` on the unfixed tree reported the 27 source
descriptions; after the fixes and regeneration it passes.
- `go test ./scripts/docgenenv/ ./scripts/clidocgen/
./scripts/docsmanifestgen/ ./scripts/styleclaims/
./scripts/apidocgen/...`
- `golangci-lint run` on the changed packages, `pnpm run check-docs`,
`go run ./scripts/styleclaims`, `scripts/check_emdash.sh`, and
`docsmanifestgen fmt` (no changes).

Linear: [DOCS-1304](https://linear.app/codercom/issue/DOCS-1304)

---

🤖 Built with AI assistance.
2026-10-20 18:51:44 -04:00

399 lines
13 KiB
Go

package docgenenv_test
import (
"io/fs"
"os"
"path/filepath"
"strings"
"testing"
"github.com/stretchr/testify/require"
"github.com/coder/coder/v2/scripts/docgenenv"
)
// writeTree writes files (sources-relative name to content) under a new docs
// directory's manifest sources and returns the docs and sources directories.
// Every route path used by the tests exists as a page under the docs dir.
func writeTree(t *testing.T, files map[string]string) (docsDir, sourcesDir string) {
t.Helper()
docsDir = t.TempDir()
sourcesDir = filepath.Join(docsDir, docgenenv.ManifestSourcesDir)
for _, page := range []string{"index.md", "ref/index.md", "ref/api/index.md", "ref/api/general.md", "ref/api/users.md"} {
p := filepath.Join(docsDir, page)
require.NoError(t, os.MkdirAll(filepath.Dir(p), 0o755))
require.NoError(t, os.WriteFile(p, []byte("# page\n"), 0o600))
}
for name, content := range files {
p := filepath.Join(sourcesDir, name)
require.NoError(t, os.MkdirAll(filepath.Dir(p), 0o755))
require.NoError(t, os.WriteFile(p, []byte(content), 0o600))
}
return docsDir, sourcesDir
}
const (
testIndex = "versions: [main]\nsections:\n - home.yml\n - ref.yml\n"
testHome = "title: Home\npath: ./index.md\n"
testRef = `title: Reference
path: ./ref/index.md
children:
- include: ref/api.yml
`
testRefAPI = `title: REST API
path: ./ref/api/index.md
children_from: generated/api.json
children:
- title: Users
description: Manage users.
state: [beta]
`
testAPI = `[{"title": "General", "path": "./ref/api/general.md"}, {"title": "Users", "path": "./ref/api/users.md"}]`
)
func validTree() map[string]string {
return map[string]string{
"index.yml": testIndex,
"home.yml": testHome,
"ref.yml": testRef,
"ref/api.yml": testRefAPI,
"generated/api.json": testAPI,
}
}
func TestBuildManifest(t *testing.T) {
t.Parallel()
docsDir, sourcesDir := writeTree(t, validTree())
m, err := docgenenv.BuildManifest(sourcesDir, docsDir)
require.NoError(t, err)
require.Equal(t, []string{"main"}, m.Versions)
require.Len(t, m.Routes, 2)
api := m.FindRoute("Reference", "REST API")
require.NotNil(t, api)
require.Empty(t, api.ChildrenFrom)
// Generated routes keep their order; the overlay fills in metadata.
require.Equal(t, []docgenenv.Route{
{Title: "General", Path: "./ref/api/general.md"},
{Title: "Users", Description: "Manage users.", Path: "./ref/api/users.md", State: []string{"beta"}},
}, api.Children)
// Keys follow the struct order and children_from never reaches the JSON.
b, err := docgenenv.MarshalJSON(api)
require.NoError(t, err)
require.NotContains(t, string(b), "children_from")
require.Regexp(t, `(?s)"title": "Users",\s*"description".*"path".*"state"`, string(b))
}
func TestBuildManifestYAMLFragment(t *testing.T) {
t.Parallel()
files := validTree()
delete(files, "generated/api.json")
files["ref/api.yml"] = `title: REST API
path: ./ref/api/index.md
children_from: generated/api.yml
`
files["generated/api.yml"] = "- title: General\n path: ./ref/api/general.md\n"
docsDir, sourcesDir := writeTree(t, files)
m, err := docgenenv.BuildManifest(sourcesDir, docsDir)
require.NoError(t, err)
require.Equal(t, []docgenenv.Route{{Title: "General", Path: "./ref/api/general.md"}}, m.FindRoute("Reference", "REST API").Children)
}
func TestLoadManifestSourcesLeavesOverlaysUnresolved(t *testing.T) {
t.Parallel()
_, sourcesDir := writeTree(t, validTree())
m, err := docgenenv.LoadManifestSources(sourcesDir)
require.NoError(t, err)
api := m.FindRoute("Reference", "REST API")
require.NotNil(t, api)
require.Equal(t, "generated/api.json", api.ChildrenFrom)
require.Equal(t, []docgenenv.Route{{Title: "Users", Description: "Manage users.", State: []string{"beta"}}}, api.Children)
}
func TestBuildManifestErrors(t *testing.T) {
t.Parallel()
for _, tc := range []struct {
name string
edit func(files map[string]string)
wantErr string
// Set for OS errors, whose text differs between platforms.
wantErrIs error
}{
{
name: "UnknownKey",
edit: func(f map[string]string) { f["home.yml"] = "title: Home\ntitel: typo\npath: ./index.md\n" },
wantErr: "field titel not found",
},
{
name: "UnknownFragmentKey",
edit: func(f map[string]string) { f["generated/api.json"] = `[{"title": "General", "paht": "x"}]` },
wantErr: `unknown field "paht"`,
},
{
name: "MissingPage",
edit: func(f map[string]string) { f["home.yml"] = "title: Home\npath: ./nope.md\n" },
wantErr: `Home: path "./nope.md" does not exist`,
},
{
name: "MissingPath",
edit: func(f map[string]string) { f["home.yml"] = "title: Home\n" },
wantErr: "home.yml: Home: route is missing a path",
},
{
name: "UnreferencedFile",
edit: func(f map[string]string) { f["orphan.yml"] = testHome },
wantErr: "orphan.yml: not listed",
},
{
name: "DuplicateSection",
edit: func(f map[string]string) { f["index.yml"] = testIndex + " - home.yml\n" },
wantErr: `section "home.yml" is listed more than once`,
},
{
name: "SectionOutsideSources",
edit: func(f map[string]string) { f["index.yml"] = "versions: [main]\nsections:\n - ../home.yml\n" },
wantErr: "must be a relative path inside the sources directory",
},
{
name: "UnmatchedOverlay",
edit: func(f map[string]string) {
f["generated/api.json"] = `[{"title": "General", "path": "./ref/api/general.md"}]`
},
wantErr: `overlay "Users" matches no route in generated/api.json`,
},
{
name: "ConflictingOverlay",
edit: func(f map[string]string) {
f["generated/api.json"] = `[{"title": "Users", "description": "Generated.", "path": "./ref/api/users.md"}]`
},
wantErr: `overlay description "Manage users." conflicts with generated "Generated."`,
},
{
name: "OverlayWithPath",
edit: func(f map[string]string) {
f["ref/api.yml"] = `title: REST API
path: ./ref/api/index.md
children_from: generated/api.json
children:
- title: Users
path: ./ref/api/users.md
`
},
wantErr: "overlays under children_from may set only",
},
{
name: "GrandchildrenInOneFile",
edit: func(f map[string]string) {
delete(f, "ref/api.yml")
f["ref.yml"] = `title: Reference
path: ./ref/index.md
children:
- title: REST API
path: ./ref/api/index.md
children:
- title: General
path: ./ref/api/general.md
`
},
wantErr: "ref.yml: Reference > REST API: a source file holds one level of children; move this route into its own file and include it",
},
{
name: "ChildWithChildrenFromInOneFile",
edit: func(f map[string]string) {
delete(f, "ref/api.yml")
f["ref.yml"] = `title: Reference
path: ./ref/index.md
children:
- title: REST API
path: ./ref/api/index.md
children_from: generated/api.json
`
},
wantErr: "move this route into its own file and include it",
},
{
name: "IncludeWithOtherKeys",
edit: func(f map[string]string) { f["ref.yml"] = testRef + " title: REST API\n" },
wantErr: `include "ref/api.yml": an include entry may set only include`,
},
{
name: "IncludedTwice",
edit: func(f map[string]string) { f["ref.yml"] = testRef + " - include: ref/api.yml\n" },
wantErr: `include "ref/api.yml": file is already listed in index.yml or included elsewhere`,
},
{
name: "IncludeSection",
edit: func(f map[string]string) { f["ref.yml"] = testRef + " - include: home.yml\n" },
wantErr: `include "home.yml": file is already listed`,
},
{
name: "IncludeOutsideSources",
edit: func(f map[string]string) { f["ref.yml"] = testRef + " - include: ../api.yml\n" },
wantErr: "must be a relative path inside the sources directory",
},
{
name: "IncludeNotYAML",
edit: func(f map[string]string) { f["ref.yml"] = testRef + " - include: generated/api.json\n" },
wantErr: `include "generated/api.json": must be a .yml file`,
},
{
name: "IncludeMissingFile",
edit: func(f map[string]string) { f["ref.yml"] = testRef + " - include: ref/nope.yml\n" },
wantErr: "nope.yml",
wantErrIs: fs.ErrNotExist,
},
{
name: "IncludeOnFileRoute",
edit: func(f map[string]string) { f["home.yml"] = testHome + "include: ref/api.yml\n" },
wantErr: "home.yml: Home: include is allowed only on a child entry",
},
{
name: "MissingPathInIncludedFile",
edit: func(f map[string]string) { f["ref/api.yml"] = "title: REST API\n" },
wantErr: "ref/api.yml: Reference > REST API: route is missing a path",
},
{
name: "UnreferencedNestedFile",
edit: func(f map[string]string) { f["ref/orphan.yml"] = testHome },
wantErr: "ref/orphan.yml: not listed",
},
{
name: "IncludeInFragment",
edit: func(f map[string]string) {
f["generated/api.json"] = `[{"title": "General", "path": "./ref/api/general.md", "include": "x.yml"}]`
},
wantErr: `unknown field "include"`,
},
{
name: "IncludeInYAMLFragment",
edit: func(f map[string]string) {
delete(f, "generated/api.json")
f["ref/api.yml"] = "title: REST API\npath: ./ref/api/index.md\nchildren_from: generated/api.yml\n"
f["generated/api.yml"] = "- title: General\n path: ./ref/api/general.md\n include: x.yml\n"
},
wantErr: "generated/api.yml: General: fragments can't set children_from or include",
},
{
name: "TrailingCommentOnDescription",
edit: func(f map[string]string) {
f["home.yml"] = "title: Home\ndescription: Use #tags here\npath: ./index.md\n"
},
wantErr: "home.yml: line 2: description has a trailing comment",
},
{
name: "DescriptionWithoutPeriod",
edit: func(f map[string]string) {
f["home.yml"] = "title: Home\ndescription: The home page\npath: ./index.md\n"
},
wantErr: `home.yml: Home: description must end with a period: "The home page"`,
},
{
name: "DescriptionWithQuestionMark",
edit: func(f map[string]string) {
f["home.yml"] = "title: Home\ndescription: Where do I start?\npath: ./index.md\n"
},
wantErr: `home.yml: Home: description must end with a period: "Where do I start?"`,
},
{
name: "ChildDescriptionWithoutPeriod",
edit: func(f map[string]string) {
f["ref.yml"] = testRef + " - title: Home again\n description: Same page\n path: ./index.md\n"
},
wantErr: `ref.yml: Reference > Home again: description must end with a period: "Same page"`,
},
{
name: "OverlayDescriptionWithoutPeriod",
edit: func(f map[string]string) {
f["ref/api.yml"] = strings.Replace(testRefAPI, "Manage users.", "Manage users", 1)
},
wantErr: `ref/api.yml: Reference > REST API > Users: description must end with a period: "Manage users"`,
},
{
name: "FragmentDescriptionWithoutPeriod",
edit: func(f map[string]string) {
f["generated/api.json"] = `[{"title": "General", "description": "General endpoints", "path": "./ref/api/general.md"}, {"title": "Users", "path": "./ref/api/users.md"}]`
},
wantErr: `generated/api.json: General: description must end with a period: "General endpoints"`,
},
{
name: "MultipleDocuments",
edit: func(f map[string]string) { f["home.yml"] = testHome + "---\n" + testHome },
wantErr: "single YAML document",
},
} {
t.Run(tc.name, func(t *testing.T) {
t.Parallel()
files := validTree()
tc.edit(files)
docsDir, sourcesDir := writeTree(t, files)
_, err := docgenenv.BuildManifest(sourcesDir, docsDir)
require.ErrorContains(t, err, tc.wantErr)
if tc.wantErrIs != nil {
require.ErrorIs(t, err, tc.wantErrIs)
}
})
}
}
func TestWriteRouteFragmentRoundTrips(t *testing.T) {
t.Parallel()
routes := []docgenenv.Route{
{Title: "Groups & Roles", Path: "./a.md", Children: []docgenenv.Route{{Title: "b", Path: "./b.md", State: []string{"premium"}}}},
}
dir := t.TempDir()
for _, name := range []string{"frag.json", "frag.yml"} {
p := filepath.Join(dir, name)
require.NoError(t, docgenenv.WriteRouteFragment(p, routes))
var got []docgenenv.Route
require.NoError(t, docgenenv.DecodeSourceFile(p, &got), name)
require.Equal(t, routes, got, name)
}
b, err := os.ReadFile(filepath.Join(dir, "frag.json"))
require.NoError(t, err)
require.Contains(t, string(b), `Groups & Roles`)
}
// TestBuildManifestFrontMatterDescription checks the description in a page's
// own front matter, which the docs site prefers over the manifest's.
func TestBuildManifestFrontMatterDescription(t *testing.T) {
t.Parallel()
for _, tc := range []struct {
name string
page string
wantErr string
}{
{name: "Period", page: "---\ntitle: Home\ndescription: The home page.\n---\n\n# page\n"},
{name: "NoDescription", page: "---\ntitle: Home\n---\n\n# page\n"},
{name: "NoFrontMatter", page: "# page\n\n---\n\ndescription: not front matter\n"},
{
name: "WithoutPeriod",
page: "---\ntitle: Home\ndescription: The home page\n---\n\n# page\n",
wantErr: `index.md: Home: front matter description must end with a period: "The home page"`,
},
{
name: "Quoted",
page: "---\ntitle: Home\ndescription: \"Show role(s)\"\n---\n\n# page\n",
wantErr: `index.md: Home: front matter description must end with a period: "Show role(s)"`,
},
} {
t.Run(tc.name, func(t *testing.T) {
t.Parallel()
docsDir, sourcesDir := writeTree(t, validTree())
require.NoError(t, os.WriteFile(filepath.Join(docsDir, "index.md"), []byte(tc.page), 0o600))
_, err := docgenenv.BuildManifest(sourcesDir, docsDir)
if tc.wantErr == "" {
require.NoError(t, err)
return
}
require.ErrorContains(t, err, tc.wantErr)
})
}
}