docs: group CLI and API reference feature docs under schema-support/#3652
Open
Mpdreamz wants to merge 2 commits into
Open
docs: group CLI and API reference feature docs under schema-support/#3652Mpdreamz wants to merge 2 commits into
Mpdreamz wants to merge 2 commits into
Conversation
Move cli-reference-how-to.md and cli-supplemental-docs.md out of docs/cli/ and api-explorer.md out of docs/configure/content-set/ into a new docs/schema-support/ folder covering both schema-driven reference generators. New structure: docs/schema-support/index.md overview + comparison + gap statement docs/schema-support/cli-schema/index.md CLI schema setup and docset.yml config docs/schema-support/cli-schema/supplemental.md naming, validation, overrides docs/schema-support/api-explorer/index.md API Explorer config, intro/outro, extensions - Overview page contrasts fine-grained CLI extension (per-command/flag/argument overrides, convention-based discovery, schema validation) with page-level API extension (intro/outro pages only, one spec per product, slug/collision validation) and documents the current gap: no per-operation/tag/schema overrides in API Explorer. - api-explorer/index.md gains a "What you can extend (and what you can't)" section, naming/validation subsection (slug rules, reserved types/tags segments, operation-moniker collisions, one-spec-per-product rule stated plainly). - cli-schema/supplemental.md gains: root index.md pattern, cmd-index exception, note on ignored non-ns-/cmd- files, deeper flat-nesting example. - docs/_docset.yml: rewire toc entries; add schema-support folder block. - docs/_redirects.yml: add three redirects for moved pages. - Fix relative links in moved files; update inbound links in navigation.md, content-set/index.md, CONTRIBUTING.md, and AGENTS.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add the three new schema-support pages to the links section and the three new redirects to the redirects section of the links.json snapshot test. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.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
1 participant
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.
Why
The feature documentation for the two schema-driven reference generators (CLI schema and API Explorer) was scattered across unrelated locations (
docs/cli/,docs/configure/content-set/), the shared "generate + extend with markdown" model was never explained in one place, and the gap between the two — the API Explorer only supports page-level intro/outro markdown while the CLI reference supports fine-grained per-command/flag/argument overrides — was completely undocumented.What
Moves the feature how-to pages into a new
docs/schema-support/section and adds an overview page that covers both generators side by side.The overview compares the two on source format, config key, generated output, markdown-extension granularity, file discovery mechanism, and validation behaviour, then states the current gap plainly: API Explorer markdown is page-level only — you cannot override an individual operation, tag, schema, or parameter description today.
The moved API Explorer page gains a "What you can extend (and what you can't)" section, a naming and validation subsection (slug derivation rule, reserved
types/tagssegments, operation-moniker collision detection, one-spec-per-product constraint), and the gap statement with a forward reference to the CLI supplemental mechanism.The moved CLI supplemental page gains accuracy fixes verified against the implementation: the root
index.mdmatch pattern (not onlyns-root.md), thecmd-indexexception for a command literally namedindex, a note that non-ns-/cmd-files are silently ignored, and a deeper three-level flat-prefix example.Redirects are added for all three moved pages. The generated CLI reference section (
docs/cli/,folder: cli) and its existing ~40 redirects are untouched.