docs: auto-generate API Reference nav from Speakeasy service pages#383
Merged
Conversation
Adds scripts/gen-docs-nav.sh (rewrites the "API Reference" group in docs/docs.json from docs/sdks/<tag>/README.mdx, alphabetical, idempotent) and a standalone .github/workflows/docs-nav.yaml that runs it and commits docs.json when docs/sdks/** changes. New API sections appear in the sidebar automatically — no manual docs.json edits. Python's docs regenerate via the reusable sdk-generation-action (no local `speakeasy run` step to hook), so nav generation is a standalone workflow here rather than an inline step.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
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.
Summary
Removes the need to hand-maintain the
API Referencepage list indocs/docs.json. New API sections appear in the sidebar automatically.scripts/gen-docs-nav.sh— globsdocs/sdks/<tag>/README.mdxand rewrites only theAPI Referencegroup'spages(alphabetical). Idempotent; errors if the group is missing; preserves$schema, theme, colors, Getting Started. Needs bash + jq (preinstalled on ubuntu runners). Identical to the script in the typescript-sdk and go-sdk PRs..github/workflows/docs-nav.yaml— standalone workflow; runs the script and commitsdocs.jsonwhendocs/sdks/**changes. Python's docs regenerate via the reusablesdk-generation-action(no localspeakeasy runstep to hook), so a standalone workflow is the right seam here.docs/docs.json— pages re-sorted alphabetically by the script.Verified locally
Test plan
docs-navruns and commits an updated docs.json when tags change