feat(tspd): add --rules-dir option to control rule reference page location#11316
Merged
Conversation
…ation Add a `--rules-dir` CLI option (and `rulesDir` API option) to `tspd doc` to control the directory where per-rule reference pages are written. Defaults to `rules` (relative to --output-dir); can be set to a path escaping the output dir (e.g. `../rules`) to keep rule pages outside the generated reference folder.
timotheeguerin
marked this pull request as ready for review
July 20, 2026 18:27
timotheeguerin
requested review from
bterlson,
catalinaperalta,
iscai-msft,
markcowl and
witemple-msft
as code owners
July 20, 2026 18:27
commit: |
timotheeguerin
enabled auto-merge
July 20, 2026 18:28
Contributor
|
All changed packages have been documented.
Show changes
|
|
You can try these changes here
|
iscai-msft
approved these changes
Jul 20, 2026
timotheeguerin
pushed a commit
to Azure/typespec-azure
that referenced
this pull request
Jul 21, 2026
The core bump pulls in tspd's per-rule reference page generation. Rather than let it orphan Azure's rich hand-written rule pages at a new location, this migrates each rule to the tspd `docs` field (rich content now lives in `packages/*/src/rules/*.md`) and passes `--rules-dir ../rules` so generated pages stay at the existing `libraries/<lib>/rules/<name>` URLs (net-zero URL change). - core: bump submodule to latest main (includes merged tspd `--rules-dir` change, microsoft/typespec#11316) - 86 rules: add `docs: fileRef.fromPackageRoot("src/rules/<name>.md")` - 3 package.json regen-docs scripts: pass `--rules-dir ../rules` - astro.config: 5 redirects for rules whose historical slug != rule name - gitignore the generated `libraries/*/rules/` pages (regenerated by build:web) - pnpm-lock: add @typespec/events / @typespec/sse workspace links (http-specs)
msyyc
pushed a commit
to JennyPng/typespec
that referenced
this pull request
Jul 21, 2026
…t#11320) ## Problem The tspd change that auto-generates one reference page per linter rule (microsoft#11221) moved the `@typespec/http` linter rule page from its historical location: - **Before:** `https://typespec.io/docs/libraries/http/rules/op-reference-container-route` - **After:** `https://typespec.io/docs/libraries/http/reference/rules/op-reference-container-route` This is a breaking change to the public documentation URL. The rule's own `url` field, external links, and the diagnostic "see documentation" link all still point at the historical `libraries/http/rules/<name>` location, which now 404s. ## Fix Use the `--rules-dir ../rules` option (added in microsoft#11316) in http's `regen-docs` script so the per-rule reference pages are written back to `libraries/http/rules/<name>`, restoring the original URL. - `packages/http/package.json` — add `--rules-dir ../rules` to `regen-docs`. - Regenerated docs: the rule page moves back to `libraries/http/rules/op-reference-container-route.md` (100% rename) and `linter.md` links back to `../rules/...`. - `current-sidebar.ts` — re-enable the http "Rules" sidebar group (`hasLinterRules: true`), which autogenerates from `libraries/http/rules`. `@typespec/http` is the only library in this repo that ships linter rules, so no other library is affected. ## Validation - `regen-docs` is stable (running it twice produces no diff). - The restored page URL `libraries/http/rules/op-reference-container-route` matches the rule's hardcoded `url` again. - `chronus verify` passes. Co-authored-by: tadelesh <chenjieshi@microsoft.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
msyyc
pushed a commit
to msyyc/typespec-azure
that referenced
this pull request
Jul 21, 2026
…Azure#4968) Bumps the `core` submodule to latest main, which pulls in tspd's per-rule reference page generation (microsoft/typespec#11221). Left as-is, that would orphan Azure's rich hand-written rule pages by emitting barebones pages at a new location. Instead, this migrates each rule to the tspd `docs` field and keeps the generated pages at their existing URLs (net-zero URL change). ## Changes - **core**: bump submodule to latest main — includes the merged tspd `--rules-dir` change (microsoft/typespec#11316) - **86 rules**: add `docs: fileRef.fromPackageRoot("src/rules/<name>.md")`; rich content now lives in `packages/*/src/rules/*.md` - **3 `package.json`** regen-docs scripts: pass `--rules-dir ../rules` so generated pages stay at `libraries/<lib>/rules/<name>` - **astro.config**: 5 redirects for rules whose historical slug differs from the rule name (e.g. `prevent-format` → `no-format`) - **.gitignore**: ignore the generated `libraries/*/rules/` pages (regenerated during `build:web`) - **pnpm-lock**: add `@typespec/events` / `@typespec/sse` workspace links (new `http-specs` peer deps from the bump) - **eng/feeds e2e**: adapt `init-templates.e2e.ts` to the compiler's new `TemplateSource` scaffold API — `ScaffoldingConfig.baseUri` was replaced by `source?: TemplateSource` (microsoft/typespec#11303). Supersedes Azure#4965. - Contributing guide, `create-linter-rule` skill + scaffolder updated to the `docs`-field workflow ## Validation - `typespec-azure-core`, `typespec-azure-resource-manager`, `typespec-client-generator-core` tests pass - `oxlint` clean - `pnpm install --frozen-lockfile` passes - `pnpm regen-docs` clean (no drift) - init-templates e2e: scaffolding tests pass via the new `TemplateSource` path (the 2 `validate` tests that `npm install` an unpublished `@azure-tools/typespec-autorest` version fail only on registry resolution, unrelated to this change) --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a
--rules-diroption (and matchingrulesDirAPI option) totspd docto control the directory where the per-rule reference pages are written.Since the tspd change that auto-generates one reference page per linter rule, those pages are always emitted under
<output-dir>/rules/. Some consumers (e.g.typespec-azure) generate their reference docs into areference/output dir but want the rule pages to keep their historical location one level up (libraries/<lib>/rules/<name>), so that existing rule URLs stay stable.This adds a small, backwards-compatible knob to control that location.
Details
--rules-dir <dir>ontspd doc.rulesDiroption onGenerateLibraryDocsOptionsandRenderToStarlightMarkdownOptions."rules"(relative to--output-dir) — no change to existing behavior."../rules") to place rule pages outside the generated reference folder.StarlightRenderer.linterRuleLink(used bylinter.md) honors the configured dir so cross-links resolve correctly.Example