mirror of
https://github.com/coder/coder.git
synced 2026-11-22 03:18:31 +08:00
main
5
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
1baff57cb0 |
fix: resolve docs and code conflicts found in the main docs audit (#32158)
## Summary Addresses 106 of the 113 conflicts between the docs and the code that the November audit of `main` found: 102 are fixed and 4 have an interim docs fix. Every finding was re-checked against the code before it was fixed. Most fixes are docs-only. Three are small code fixes where the docs described the intended behavior and the code was wrong, each in its own commits so it can be split out. No change in this PR alters template build or agent behavior. ## Changes Fixes by area (finding counts): templates 28, install 13, integrations and monitoring 13, auth and security 12, networking 11, Coder Agents 9, AI governance 7, reference 7, workspaces 6. Code fixes. Each needs a look from the code owner. If an owner prefers not to take one, drop its commits and I will change the docs to describe the current behavior instead. | Commits | Change | Risk to check | |---------|--------|---------------| | `fix: keep built-in listener defaults in packaged coder.env`, and three follow-up commits | `coder.env` comments out `CODER_HTTP_ADDRESS=` and the three `CODER_TLS_*` lines, so an untouched package install listens on `127.0.0.1:3000` as the docs say. Only the `CODER_HTTP_ADDRESS=` line changed behavior. The TLS options default to empty, so commenting them out is for consistency. The Lima examples rewrite the commented line and fail if the line is not found. A test compares every option that the file sets against the built-in defaults. | The deb and RPM packages were not built or installed. Every released package through v2.39.0 ships the empty line, and upgrades keep an existing file (`config\|noreplace`), so the upgrade pages now say how to fix it. | | `fix(cli/clilog): accept log sinks that are all disabled`, and three follow-up commits | `--log-human=/dev/null` with no other log location no longer fails with "no loggers provided". It is the documented way to disable logging. An empty location still fails with that error when no other sink is set, as before. | Behavior change: with `/dev/null`, the server and the provisioner daemon can start with no log output. | | `fix(cli): detect CODER_PROC_PRIO_MGMT by presence`, and a comment follow-up | Log line only. With the variable set to an empty value, the agent now logs that process priority management is enabled, which is what `agentexec` already does. No detection or behavior change. | Low. | Two option descriptions in `codersdk/deployment.go` are corrected, with the CLI reference, configuration reference, and golden files regenerated: the default quiet hours schedule (the max deadline is the quiet hours window on the next day that the template's autostop requirement applies) and `--experiments` (`*` opts in to the experiments marked safe, also in `enterprise/cli/provisionerdaemonstart.go`). ### Code fixes that were reverted after review Two code fixes from the first version of this PR are reverted in the branch. The net diff has no change under `agent/` or `coderd/`. The docs now describe what the code does, and both issues stay open for the owner. - **`error` merge strategy for `coder_env` (DOCS-1669).** The fix made `merge_strategy = "error"` fail whenever a name was set twice, whatever the resource order. Existing template versions that pair an `error` entry with a later `replace` or `append` entry would start to fail every build after `terraform apply`. That is a breaking change that needs its own PR and release note. The fix and its tests are in `dff8e7c6ce` and can be cherry-picked. `environment-variables.md` now says the check runs only when the `error` resource is processed. - **Nice value before the capability drop (DOCS-1687).** The fix let `coder agent-exec` apply a negative nice value by calling `setpriority` before it drops effective capabilities. The current order is deliberate: with the fix, any local process could run the agent binary with `--coder-nice=-20` when the binary has the `CAP_SYS_NICE` file capability. `process-priority.md` now says a nice value below the agent's own is not applied, and no longer tells admins to grant `CAP_SYS_NICE`. ## Not included Seven findings are left out. - DOCS-1629: covered by #31639. - DOCS-1703 and DOCS-1724: covered by #31980. - DOCS-1584, DOCS-1683, DOCS-1685, DOCS-1686: each needs an owner decision, and no neutral docs wording exists until that decision is made. The validation comment on each issue names the decision. Four fixes are interim, so their issues stay open: - DOCS-1600: the AI Gateway pages now agree that the legacy metric names are deprecated and "will be removed in a future release". The code still emits them, and its TODO names v2.37, which has shipped. The owner still needs to set the removal release. - DOCS-1689: the page now says **New Template** opens the builder only for users with the Owner role, because the page gates on read access to the deployment config. Whether Template Admins should get the builder is still open. - DOCS-1669 and DOCS-1687: docs-only for now. Refer to [Code fixes that were reverted after review](#code-fixes-that-were-reverted-after-review). ## Review notes - Claims that describe product intent and need an owner's yes: the Premium qualifier on per-organization workspace sharing (the API route has no license check, the dashboard needs multiple organizations), `organization` port sharing in OSS, the telemetry field list, and the `1-5` cron range in the prebuilds schedule example. - Not run end to end: the PostgreSQL TLS procedure on a cluster, the OpenShift and air-gapped examples, the BSD `date` and `tar` forms on macOS, the Windows command on the multiple Kubernetes clusters page, and the keep-alive script in `docs/reference/index.md` (only its comparison logic was run, against sample values). Nothing was checked on a live deployment. - Likely merge conflicts with open PRs: #31990 (`mcp-server.md`, `feature-stages.md`, `docker-in-workspaces.md`), #31982 (`workspace-management.md`), #31980 (`health-check.md`), #31977 (`manage-provisioner-jobs.md`), #31869 (`airgap.md`), #30486 (`add-envbuilder.md`), and #31326 and #31531 (`codersdk/deployment.go` and generated files). ## Testing - `make pre-commit` (gen, fmt, lint, slim build), before the PR opened and again after the review changes. - `go test` for `./cli/clilog/...`, `./codersdk/`, `./cli/` (`TestServer`, `TestAgent`, and golden files), and `./enterprise/cli/` (provisioner, server, and help golden files). `./agent/agentexec/...` and `./coderd/provisionerdserver/...` pass after the reverts. Linux only. CI covers macOS and Windows. - The `coder.env` test fails against the file on `main` and passes against the new one. It reads the file with `godotenv`, which accepts CRLF line endings. - An empty `CODER_HTTP_ADDRESS=` was confirmed end to end with a full build of the server (output below). - The new `sed` and `grep` lines in the Lima examples were run with GNU tools against the old and the new form of `coder.env`. The Lima VMs were not started. - `--log-human=/dev/null` and `CODER_LOGGING_HUMAN=` were confirmed with the same build (output below). - `coder agent-exec --coder-nice=-5 -- echo` from a full build, as a non-root user: `coder-agent: failed to adjust niceness to -5 ...: permission denied` on stderr, the command output on stdout, exit code 0. - `postgres-ssl.md` rendered with the GitHub Markdown API: two ordered lists with three and five items, where `main` has six lists. - markdownlint, the table formatter, `make lint/emdash`, `make lint/docs-html`, `make lint/docs-manifest`, `make lint/docs-redirects`, `make lint/style-claims`, and Vale on the changed lines. - A doc-check self-review of the docs diff by four independent reviewers. It found six problems, which are fixed. The accuracy and coverage lenses ran on every area. The language and structure lenses ran in full on only part of the diff. <details> <summary>Test and terminal output for the code fixes (Linux)</summary> ```console $ go test ./codersdk/ -run TestPackagedCoderEnvKeepsDefaults -count=1 -v --- PASS: TestPackagedCoderEnvKeepsDefaults (0.00s) ok github.com/coder/coder/v2/codersdk 0.071s $ go test ./cli/clilog/ -run TestBuilder -count=1 -v --- PASS: TestBuilder (0.00s) --- PASS: TestBuilder/NoSinks (0.00s) --- PASS: TestBuilder/NoSinks/JSONDevNull (0.00s) --- PASS: TestBuilder/NoSinks/StackdriverDevNull (0.00s) --- PASS: TestBuilder/NoSinks/NoConfiguration (0.00s) --- PASS: TestBuilder/NoSinks/HumanDevNull (0.00s) --- PASS: TestBuilder/WithHuman (0.00s) --- PASS: TestBuilder/WithFilter (0.00s) --- PASS: TestBuilder/WithJSON (0.00s) --- PASS: TestBuilder/Verbose (0.00s) --- PASS: TestBuilder/FromDeploymentValues (0.01s) --- PASS: TestBuilder/FromDeploymentValues/Defaults (0.00s) --- PASS: TestBuilder/FromDeploymentValues/EmptyHumanEnv (0.00s) --- PASS: TestBuilder/FromDeploymentValues/Override (0.00s) ok github.com/coder/coder/v2/cli/clilog 0.171s $ TMPDIR=$HOME/.cache/agentexec-tmp go test ./agent/agentexec/... ./coderd/provisionerdserver/... -count=1 ok github.com/coder/coder/v2/agent/agentexec 4.236s ok github.com/coder/coder/v2/coderd/provisionerdserver 2.404s # Full build of the server (go build ./cmd/coder). An empty value stops it before it connects to the database. $ CODER_HTTP_ADDRESS= coder server --postgres-url 'postgres://127.0.0.1:1/x?sslmode=disable' Encountered an error running "coder server", see "coder server --help" for more information error: TLS is disabled. Enable with --tls-enable or specify a HTTP address # With the variable unset, the server passes that check and goes on to the database. $ coder server --postgres-url 'postgres://127.0.0.1:1/x?sslmode=disable' 2026-11-13 02:19:41.901 [warn] ping postgres: retrying error="dial tcp 127.0.0.1:1: connect: connection refused" try=11 Encountered an error running "coder server", see "coder server --help" for more information error: connect to postgres: connect to postgres: unable to connect after 11 tries; last error: dial tcp 127.0.0.1:1: connect: connection refused # An empty log location with no other sink still stops the server. $ CODER_LOGGING_HUMAN= coder server --postgres-url 'postgres://127.0.0.1:1/x?sslmode=disable' Encountered an error running "coder server", see "coder server --help" for more information error: make logger: no loggers provided, use /dev/null to disable logging # /dev/null passes the logger check. The server prints no log lines and goes on to the database. $ coder server --log-human=/dev/null --postgres-url 'postgres://127.0.0.1:1/x?sslmode=disable' Encountered an error running "coder server", see "coder server --help" for more information error: connect to postgres: connect to postgres: unable to connect after 11 tries; last error: dial tcp 127.0.0.1:1: connect: connection refused ``` </details> ## Linear Fixes DOCS-1583, DOCS-1585, DOCS-1586, DOCS-1587, DOCS-1588, DOCS-1589, DOCS-1590, DOCS-1591, DOCS-1592, DOCS-1593, DOCS-1594, DOCS-1595, DOCS-1596, DOCS-1597, DOCS-1598, DOCS-1599, DOCS-1601, DOCS-1602, DOCS-1603, DOCS-1604, DOCS-1605, DOCS-1606, DOCS-1607, DOCS-1608, DOCS-1609, DOCS-1614, DOCS-1618, DOCS-1619, DOCS-1620, DOCS-1624, DOCS-1635, DOCS-1639, DOCS-1644, DOCS-1651, DOCS-1652, DOCS-1653, DOCS-1654, DOCS-1655, DOCS-1656, DOCS-1657, DOCS-1658, DOCS-1659, DOCS-1660, DOCS-1661, DOCS-1662, DOCS-1663, DOCS-1664, DOCS-1665, DOCS-1666, DOCS-1667, DOCS-1668, DOCS-1670, DOCS-1671, DOCS-1672, DOCS-1673, DOCS-1674, DOCS-1675, DOCS-1676, DOCS-1677, DOCS-1678, DOCS-1679, DOCS-1680, DOCS-1681, DOCS-1682, DOCS-1684, DOCS-1688, DOCS-1690, DOCS-1691, DOCS-1692, DOCS-1693, DOCS-1694, DOCS-1695, DOCS-1696, DOCS-1697, DOCS-1698, DOCS-1699, DOCS-1700, DOCS-1701, DOCS-1702, DOCS-1704, DOCS-1705, DOCS-1706, DOCS-1707, DOCS-1708, DOCS-1709, DOCS-1710, DOCS-1711, DOCS-1712, DOCS-1713, DOCS-1714, DOCS-1715, DOCS-1716, DOCS-1717, DOCS-1718, DOCS-1719, DOCS-1720, DOCS-1721, DOCS-1722, DOCS-1723, DOCS-1725, DOCS-1726, DOCS-1727 Part of DOCS-1600, DOCS-1689, DOCS-1669, DOCS-1687 <details> <summary>Decision log</summary> ### Scope - One PR for all findings, as agreed with the reviewer. The code fixes are separate commits so an owner can ask for any of them to move to its own PR. Nothing in the PR is a breaking change, so the title has no `!`. - A finding was skipped only when an open PR already covers it, or when every available wording would assert an undecided product behavior. - Each validation comment on the Linear issues records the evidence, the corrections to the original finding, and what was not verified. ### Docs or code - The default was a docs-only fix that describes what the code does. - A code fix was chosen when the docs describe a behavior the code plainly intended and the code change is small and testable: the packaged env file, the log sink check, and the log line for the environment variable presence check. - The `error` merge strategy and the nice value ordering started as code fixes and went back to docs-only after review. The first breaks existing template versions. The second weakens a deliberate security ordering. - The SCIM `userName` finding (DOCS-1609) took the docs path. The handler is unchanged. ### Wording choices worth a second look - `feature-stages.md` says `--experiments=*` enables only the experiments marked safe, and points to the "Get safe experiments" API. It does not list the other experiments, because the list would drift and those experiments are hidden on purpose. The `--experiments` flag help now says the same. - `agent-metadata.md` replaces the writes-per-second formula with a description of the batcher (each server replica writes one statement every 5 seconds, or sooner at 500 entries). - `extending-templates/index.md` no longer calls `startup_script` deprecated. The provider documents it as an alias for a `coder_script`. - `postgres-ssl.md` separates client verification from server verification, so the server verification steps work alone. - `rpm.md`, `upgrade.md`, and the 2.29 to 2.34 ESR upgrade page explain the empty `CODER_HTTP_ADDRESS=` line that older packages shipped, because upgrades keep the old file. The behavior changed in v2.34.0 with the serpent upgrade in #24926. - The keep-alive script in `docs/reference/index.md` reads the current deadline and skips the request when it is already later. The comparison is on text, so it applies only when the API returns a UTC timestamp, which needs the database to use the UTC time zone. Otherwise the script sets the deadline on every pass, as it did before, and the page says so. - `external-auth.md` anchors the new GitHub Enterprise regex example. The older unanchored examples on that page and on `git-providers.md` are not changed here. ### Self-review findings that were rejected - "The builder opens for Template Admins": the Templates page needs a successful deployment config read, which the Template Admin role does not have. - "Organization Admins can set AI model prices": the price write authorizes against a site-level object, which organization-scoped grants do not match. - "The provisioner chart sets no default resources": `helm/libcoder/templates/_coder.yaml` applies 2000m and 4096Mi when `coder.resources` is empty. ### Automated review, round 1 The `coder-agents-review` app left 45 findings on `8853332`. Fixed: the two reverts above, the anchored regex, the `coder.env` follow-ups (Lima examples, upgrade notes, a comment in the file, and a test that covers every option in the file), the clilog change, the two option descriptions, and the docs findings (CORS behavior, token lifetime example, keep-alive script, agent metadata, refresh token errors, `switch` form type, `dbcrypt` skip list, and a stray line in a YAML example). Declined, with the reason on each thread: - Refactoring the `agentexec` logging and renaming its log field: not related to a docs conflict. - Rewording the "process priority management not enabled (linux-only)" log message: the docs quote the message, and the wording predates this PR. - Problems in code and docs that this PR does not change (the `Capabilities` subtest, the Helm values comment, the AWS provider path in `airgap.md`, and others in the review's out-of-scope list). ### Automated review, round 2 The app left 14 new findings on `04925bd`, and accepted the three declined threads on `cli/agent.go`. All 14 are fixed. The main one: the round 1 change that removed the "no loggers provided" error went too far, because an empty log location would then start a server with no logs. The error is back for every case except `/dev/null`. Reported by the app as out of scope and not changed: the swagger annotation for `GET /api/v2/experiments/available` declares an array, but the handler returns an object with a `safe` array. Three Storybook fixtures keep the old `--experiments` description. ### Automated review, round 3 The app confirmed that all round 2 findings are fixed, and left 10 small findings on `f55cb6d` (8 P4, 2 Nit). All are fixed: the TLS condition and the release range in the `coder.env` notes, one place for the `/dev/null` rule in `clilog`, two test cases, a clearer test failure, and the CPU example in `agent-metadata.md`. ### Automated review, rounds 4 and 5 Round 4 left one P4 on `8fffb38` (name the `--trace` option in the logging note), which is fixed. Round 5 on `2ce754e` reports no new findings and says every earlier finding is fixed or closed. The app did not post an approval: it leaves its out-of-scope items and the code fixes to a human reviewer. Two threads on `cli/agent.go` stay open on purpose for the code owner. ### Doc-check review The doc-check workflow left 12 comments on `2ce754e` (10 blocking, 2 suggestions). All are fixed in `c888885`: "refer to" or "visit" in place of "see" for cross-references on the lines this PR added, the **New template** label as the dashboard shows it, one instruction per step in the server verification procedure of `postgres-ssl.md`, and two wording changes in `process-priority.md`. The `CAP_SYS_NICE` sentence keeps a short reason, which differs from the suggested text. The `coder-agents-review` app then reviewed that commit (rounds 6 and 7). Round 6 left two P4 findings, fixed in `30b2c79`: the `failed to adjust niceness` message is described once, in the troubleshooting entry, with where it appears, and the client verification steps in `postgres-ssl.md` render as one numbered list. Round 7 reports no new findings. `2a6035c` then softens one sentence from that fix, because the agent logs the stderr of devcontainer CLI commands. The app was not run again on that commit. ### Adjacent gaps found and not fixed here - `add-envbuilder.md` has the same `zip` command that `template-from-scratch.md` had. - `template-from-scratch.md` leaves the reader in `build/` after `cd $_`, before a step that runs from `template-tour`. </details> --- _Generated by Coder Agents on behalf of @nickvigilante._ --------- Co-authored-by: Ben Potter <me@bpmct.net> |
||
|
|
3def3bf5a3 |
feat: add JSON output to coder provisioner keys create (#30152)
Uses the `cliui` output helpers from #30508. `coder provisioner keys create` printed the new key's secret as prose, so scripts provisioning external provisioners had to scrape it and look up the key's ID and tags separately. It now accepts `-o text|json`. JSON is the key as `provisioner keys list` shows it (ID, name, organization, tags, created at) plus the one-time `key`. **Behavior change:** Additive. Default text output is unchanged. The command now fetches the new key's metadata with the returned secret (`GET /api/v2/provisionerkeys/{key}`). If that fails, it prints a warning to stderr, falls back to the name, organization and tags it sent (leaving `id` and `created_at` unset), and still outputs the secret. <details> <summary>Decisions</summary> - `CreateProvisionerKey` only returns the secret, so the key's metadata comes from `GetProvisionerKey(secret)`, the same lookup `coder provisioner start` uses. This replaced an earlier list-and-match-by-name approach, per review. - A failed lookup never fails the command, because the key already exists and the secret can't be shown again. </details> Closes [CLI-36](https://linear.app/codercom/issue/CLI-36) _This PR was generated by Coder Agents on behalf of @nickvigilante._ --------- Co-authored-by: Jeremy Ruppel <jeremyruppel@users.noreply.github.com> |
||
|
|
6e51c66a97 |
docs: give every table header cell text and fail lint on empty ones (#30879)
## Summary axe reports `empty-table-header` on 116 generated CLI reference pages and several hand-written pages: a header cell with no text is announced by screen readers as an unnamed column. This PR gives every table header cell in `docs/` text, and adds a lint check so empty header cells can't come back. ## How to review this PR - `docs/reference/cli/`: 116 files, these all generate identically, so I would only spot check 2-3 of them and skip the rest - `docs/*` outside of `docs/reference/cli/`: 6 files, normal review of these - `scripts`: 5 files, code review of the Bash and Go files to make sure we're properly inserting headers into each table ## What changed **Generator.** `scripts/clidocgen` wrote an empty header row (`| | |`) over each option's metadata table (Type, Environment, YAML, Default). It now writes `| Property | Value |`. Subcommand tables already had `Name | Purpose` and are unchanged. Regenerated with `make docs/reference/cli/index.md`: 116 files under `docs/reference/cli/` change. The header rows change, and the body rows of each option table are re-padded to the wider first column; the content is otherwise identical. Every option on those 116 pages now shows a visible `Property | Value` header row above Type, Environment, YAML, and Default, so this is a visual change on the docs site as well as a screen reader one. The CLI's own `--help` output doesn't use this template, so it's unchanged. **Audit logs.** `docs/admin/security/audit-logs.md` already has `Field | Tracked` headers on `main` (the generator writes them), so there was nothing to change there; the live-site finding predates that. **Hand-written tables.** - `docs/admin/networking/port-forwarding.md`: the CORS matrix had three empty spanning corner cells. The corner now reads `From user` and `From workspace` (spanning the three row-header columns, beside the Alice/Bob and Workspace rows) and `To user`, `To workspace`, `To app` (over the three row-header columns). The grid is still 3 header rows by 7 columns. The From cells have `scope="row"` and the other header-row cells `scope="col"`, so the From labels don't become column headers for the body's label columns; the body's user, workspace, and app labels are `<th scope="row">`; and a `<caption>` says columns are the origin and rows the destination. - `groups-roles.md`, `airgap.md`, `scale-testing.md`, `workspace-tags.md`: these four corner cells are already filled by #30873. The new check would fail CI without them, so this PR carries the same four lines, byte-identical to #30873 (`Permission`, `Component`, `Scenario`, `Input`), so whichever PR merges second rebases without conflict. If #30873 merges first, these hunks drop out. **New check.** `scripts/docshtmlcheck` (`make lint/docs-html`, part of `make lint`) now also reports `empty-table-header`. I put it there because that checker already parses every Markdown file under `docs/`, generated pages included, with goldmark and tokenizes raw HTML with `golang.org/x/net/html`, and it already runs in CI. A markdownlint custom rule would have needed a new JS rule and HTML parsing there. - Markdown pipe tables: the header row, via goldmark's GFM table extension. - Raw HTML tables: every `<th>`, tracked across HTML blocks, with entities decoded and whitespace trimmed, so `<th></th>`, `<th> </th>`, and `<th><br></th>` are all reported. Markdown between the HTML blocks of an open `<th>` counts as its text. Tables in code blocks are ignored. - Output: `docs/x.md:29: empty-table-header: header cell 1 has no text (table's first header "Auditor")`, plus a summary footer. - The tokenizer loop moved out of `scanNode` into a shared `tokenizeSegments` helper so both checks use it; `scanNode`'s behavior is unchanged. - The style guide's checks table gets one row; the README for the checker describes the rule. ## Testing - Tests first: `TestCheckTables` (now 22 cases) and `TestRunEmptyTableHeader` failed against a stub, then pass. The existing `docshtmlcheck` tests pass unchanged. - `go run ./scripts/docshtmlcheck` on `main` reports 1,561 empty header cells (116 CLI pages, port-forwarding, and the four #30873 tables); on this branch it reports none. - `go test ./scripts/docshtmlcheck/ ./scripts/clidocgen/ ./scripts/docgenenv/`, golangci-lint on the changed packages, `make lint/docs-html lint/docs-manifest lint/docs-gen-filter lint/emdash`, `pnpm run check-docs`, and Vale on the changed hand-written pages all pass. - `make gen` couldn't run to completion locally (no `protoc-gen-go`); CI's gen check covers it. The CLI pages were regenerated with the repo's own target. Review feedback applied in |
||
|
|
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. |
||
|
|
d40e24cf7d |
docs: nest the CLI reference by subcommand (#29956)
## Summary Nests the CLI reference by subcommand so the Command Line sidebar collapses from 156 flat entries to 49 top-level verbs. Each page's URL follows the invocation, its page title is the full command as inline code, and its sidebar label is only its own verb as inline code. | | Before | After | | --- | --- | --- | | File | `docs/reference/cli/oauth2-provider_dcr_disable.md` | `docs/reference/cli/oauth2-provider/dcr/disable.md` | | URL | `/reference/cli/oauth2-provider_dcr_disable` | `/reference/cli/oauth2-provider/dcr/disable` | | Page title (front matter) | `oauth2-provider dcr disable` | `` `coder oauth2-provider dcr disable` `` | | Sidebar label (manifest) | `oauth2-provider dcr disable` | `` `disable` `` | Resolves DOCS-140 (coder/coder half). Also fixes the Makefile part of DOCS-1073 / DOCS-912, which this change depends on. ## Changes - `scripts/clidocgen`: pages nest by command path. A command with visible subcommands becomes its directory's `index.md`, so `oauth2-provider/index.md` and `oauth2-provider/dcr/index.md` sit above `oauth2-provider/dcr/disable.md`. Subcommand table links are relative to the parent page. - `scripts/clidocgen`: the manifest "Command Line" section is built from the command tree (nested, sorted by name, hidden commands skipped) instead of a flat list. The redundant `coder` child that pointed back at `reference/cli/index.md` is gone. - `Makefile`: the CLI rule now replaces `docs/reference/cli/` wholesale, so stale pages get removed. The manifest rule now runs `clidocgen -manifest-only` on top of the API staging manifest, so the CLI nav is generated instead of edited by hand. As a result, the nine pages that had no nav entry (`ai-gateway*`, `secret enable/disable`, `server fix-oidc-links`) now have one. - `scripts/configdocgen` and 48 prose pages: links point at the new paths (for example `reference/cli/server.md` is now `reference/cli/server/index.md`). ## How to review/QA this PR - `docs/reference/cli/**/*` (approximately 190 pages): Each of these pages are generated automatically. Some pages appear deleted, and some pages appear new. Every deleted page corresponds to a new page somewhere else, so no information is being deleted. The docs in this section should adhere to the following, so a test in the build preview for each of these items should be satisfactory: - [ ] Each subcommand of a command gets nested as a child instead of being displayed as a flat list. - [ ] Each parent command is stored in an `index.md` file. - [ ] The title of each page inside the page should now feature the full `coder XYZ` command. - [ ] The title of each page inside the page should now be formatted as inline code. - [ ] The title of each page in the sidebar should be the most granular subcommand of the whole command string (if the page's title is `coder ai-gateway keys create`, the sidebar label is `create`). - [ ] The title of each page in the sidebar should now be formatted as inline code. - [ ] The page slug for each page is now the most granular subcommand. - [ ] All links now point to the correct page. - `docs/manifest.json`: The changes here reflect the updated structure of the `docs/reference/cli` section. - `docs/**/*.md` outside of `docs/reference/cli/**/*` (approximately 50 pages): The extent of the changes in these pages are just updating the paths to point to the new page locations. - [ ] The links on the page all point to the correct new path in `docs/reference/cli`. - `scripts/clidocgen` (4 files): This is the Go code responsible for generating everything inside of `docs/reference/cli/**/*`. A typical code review here should be satisfactory. - `scripts/configdocgen` (2 files): these two files just have updates to the raw `.md` path used by `docs/admin/setup/configuration-reference.md` and updates the tests to reflect that. - `Makefile`: This updates the `make` targets for generating the CLI docs to fit the new structure. ## Merge ordering Without the renderer PRs deployed, both docs sites show literal backticks in titles and sidebar labels. Without the redirects, the old flat URLs return 404. 1. Deploy before merging this PR: coder/docs-engine#176 (beta-docs renders these titles as inline code) and coder/coder.com#1111 (classic docs renders them as inline code). Both are safe to ship first, because titles without backticks render as before. 2. Merge this PR. 3. Merge coder/coder.com#1112 (redirects from the old flat URLs) only once this content reaches the mainline release branch that serves unversioned `/docs`. ## Testing - `go test ./scripts/clidocgen/ ./scripts/configdocgen/ ./scripts/docshtmlcheck/`: pass. New tests cover page paths, subcommand links, the nested manifest, and front matter quoting. - `make docs/reference/cli/index.md docs/manifest.json docs/admin/setup/configuration-reference.md`, then a forced rerun: the second run produced no diff. - Checked the manifest: all 164 CLI entries resolve to a file, no page is missing a nav entry, and everything outside "Command Line" is byte-identical. - Relative `.md` links across `docs/`: 0 broken, same as `main`. - `make pre-commit` and `make pre-push`: pass. On earlier pre-push attempts, different unrelated vitest files timed out under host load. Those files pass when run alone, and the final push passed with `PARALLEL_JOBS=1`. <details> <summary>Implementation plan and decision log</summary> **Goal (from DOCS-140 and the requester):** URLs follow the command hierarchy. Pages are titled with the full command, and sidebar entries with the last verb only. Both are formatted as inline code. **Contract with the renderers:** a title wrapped entirely in one pair of backticks (``^`[^`]+`$``) renders as inline code. Plain-text consumers (`<title>`, meta, search, llms corpus) strip the backticks. Page title comes from front matter `title`, and the sidebar label from the manifest node `title`. **Decisions** - A parent command is `dir/index.md` rather than a sibling `dir.md`. The root CLI page is already `index.md`, and both docs-engine and the legacy coder.com renderer map `x/index.md` to `/x`. - The manifest is built from the command tree, not from the written files, so ordering is deterministic and the nesting matches the pages exactly. - The manifest discard bug (DOCS-1073 item 1) is fixed here, because without that fix the generated nested manifest would never reach the tree. DOCS-1073 items 2 through 4 (a prose fix and a hidden-command policy) are out of scope. - `-manifest-only` keeps the existing parallel `make gen` layout: the API rule still owns `_gen/manifest-staging.json`, and CLI regeneration doesn't retrigger swag. - The renderer and redirect work lives in the companion PRs in coder/docs-engine and coder/coder.com. It is linked above and not duplicated here. </details> --- > [!NOTE] > Generated by Coder Agents on behalf of @nickvigilante. |