feat: honor paths.yaml include_groups in generated error pages#1220
Closed
dawnho wants to merge 1 commit into
Closed
feat: honor paths.yaml include_groups in generated error pages#1220dawnho wants to merge 1 commit into
dawnho wants to merge 1 commit into
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
The Mintlify error/warning page generator ignored the `include_groups` filter
in codegen/data/paths.yaml, so its pages diverged from the GitBook API
reference in two ways:
- Device sub-category pages (locks, thermostats) had no page of their own, or
once added listed only each type's specific variant group. GitBook showed
the universal (ungrouped) device codes plus the type's configured groups —
e.g. thermostats had 23 codes (device_offline, account_disconnected, …), not
just the 2 thermostat-specific ones; locks had 39, not 10.
- Resource pages that DO have a filter (access_codes, access_codes/unmanaged)
over-included: they showed every group, surfacing a stray `thermostats`
group code (`auxiliary_heat_running`) that GitBook excluded.
paths.yaml is already loaded by the Mintlify pipeline as pathMetadata, so this
drives the exact same config via one rule mirroring the legacy groupVariants:
include_groups set → keep universal codes + listed groups, flattened into one
code-sorted list; unset → keep every group with its subheading.
Applied to:
- /locks → universal + locks + access_codes groups (10 → 39)
- /thermostats → universal + thermostats group (2 → 23)
- /access_codes, /access_codes/unmanaged → drop the stray thermostats code
and flatten (now match GitBook exactly, 35 codes each)
- /phones → unchanged (its own group's warning; no include_groups
upstream, and a phone is distinct from a lock/thermostat)
Generated code sets now match the GitBook pages exactly. Resources without a
filter (devices, acs/*, connected_accounts, …) are unchanged.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
dawnho
force-pushed
the
claude/error-pages-include-groups-parity
branch
from
4b6e099 to
2ce61be
Compare
dawnho
changed the title
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.
Background
Follow-up to #1219 (merged), which added Errors and Warnings pages for device sub-categories. This PR makes the generated error pages honor the
include_groupsfilter incodegen/data/paths.yaml, which the Mintlify generator ignored — causing two kinds of divergence from the old GitBook API reference.Problem
1. Device sub-category pages were too thin. GitBook showed universal (ungrouped) device codes + the type's configured groups; the generator showed only the type's own group.
/thermostats/locksThe thermostat page omitted
device_offline,account_disconnected,hub_disconnected— the errors a thermostat actually reports most often.2. Resource pages with a filter over-included.
/access_codesand/access_codes/unmanagedhaveinclude_groups: [locks, access_codes], but the generator emitted every group — surfacing a straythermostats-group code,auxiliary_heat_running("auxiliary heat is running"), on the access-code error pages. GitBook excluded it.Fix
paths.yamlis already loaded by the Mintlify pipeline aspathMetadata, so this drives the exact same config via one rule mirroring the legacygroupVariants(codegen/lib/layout/api-route.ts):Applied to:
/locks→ universal +locks+access_codes(10 → 39)/thermostats→ universal +thermostats(2 → 23)/access_codes,/access_codes/unmanaged→ drop the strayauxiliary_heat_runningand flatten (now 35 codes each, matching GitBook exactly)/phones→ unchanged (its own group's warning; noinclude_groupsupstream, and a phone is a distinct concept from a lock/thermostat device)Generated code sets now match the GitBook pages exactly (verified per page). Resources without a filter (
devices,acs/*,connected_accounts, …) are unchanged.Verification
npm run typecheck+ scopedeslint/prettier --checkpass.npm run generate:mintlifyis idempotent; the only excluded side effect isopenapi.jsoncode-sample reformatting (missingruff/shfmt/streeformatters), unrelated to this change.errors.ts),generate.ts,load-data.ts(path-metadata type), and 4 regenerated pages (locks, thermostats, access_codes, access_codes/unmanaged).🤖 Generated with Claude Code