chore: improve API docs structure with dedicated index.md files#10472
chore: improve API docs structure with dedicated index.md files#10472gitKrystan wants to merge 3 commits intomainfrom
Conversation
gitKrystan
added
🎯 canary
| display: none !important; | ||
| } | ||
|
|
||
| .VPSidebarItem .level-1 > .item > p.text { |
There was a problem hiding this comment.
This selector wasn't working before. The Universal Packages and Framework Packages headers in the sidebar are a bit sharper w/ this change.
| link: '/api/', | ||
| items: [ | ||
| { text: 'Universal' }, | ||
| { text: 'Universal Packages' }, |
There was a problem hiding this comment.
A bit more clear, plus a closer match to what shows up on /api/ when you click the API Docs link from the homepage.
| collapsed: true, | ||
| // link: '/api/', | ||
| // Ensures that this sidebar item is active when you load /api/ or any of its sub-pages | ||
| link: '/api/', |
There was a problem hiding this comment.
This makes it so that when you when you click the API Docs link (to /api/) from the homepage, the API Docs section of the sidebar is active and expanded.
| }, | ||
| { | ||
| text: 'Legacy Packages', | ||
| text: 'Legacy API Docs', |
There was a problem hiding this comment.
I toyed w/ moving this under API Docs but I think it does make sense to keep it separate so that if we end up compiling (for LLMs) "Modern API Docs" separately from "Legacy API Docs", there's a clearer distinction in the UI. I changed the name here though so that the sidebar reads:
API DocsLegacy API Docs
which reduced my cognitive overhead of "What is docs vs packages?" when reading the sidebar.
|
|
||
| // generate the API documentation | ||
| const apiDocumentation = `${ApiDocumentation}\n\n## Main Packages\n\n${MainPackages.join('\n')}\n\n## Framework Packages\n\n${FrameworkPackages.join('\n')}\n\n## Legacy Packages\n\n${OldPackages.join('\n')}\n\n`; | ||
| const apiDocumentation = `${ApiDocumentation}\n\n## Universal Packages\n\n${MainPackages.join('\n')}\n\n## Framework Packages\n\n${FrameworkPackages.join('\n')}\n\n## Legacy Packages\n\n${OldPackages.join('\n')}\n\n`; |
There was a problem hiding this comment.
Making it match sidebar.
| // if the file is in @warp-drive/legacy add the legacy badge | ||
| if (file.includes('@warp-drive/legacy')) { | ||
| // if the file is in a legacy package add the legacy badge | ||
| const isLegacyPackage = OLD_PACKAGES.some((pkg) => file.includes(pkg)) || file.includes('@warp-drive/legacy'); |
There was a problem hiding this comment.
More little red badges for stuff you should avoid using in new projects.
|
|
||
| <br> | ||
|
|
||
| --- |
There was a problem hiding this comment.
Sorry. these gaps looked weird
There was a problem hiding this comment.
@mergeModuleWith <project>
^ this is the secret sauce for not having the index ones show up
2 participants
Summary
Improves the structure and organization of legacy API documentation.
Changes
index.tstoindex.mdfiles for:@ember-data/store@ember-data/json-api@ember-data/serializer@ember-data/tracking@ember-data/model@warp-drive/build-config/indexlink in the sidebar separately.docs-viewer/docs.warp-drive.io/.vitepress/theme/custom.css,docs-viewer/docs.warp-drive.io/.vitepress/config.mts,docs-viewer/src/site-utils.tsto improve API Docs sidebar navDocumentation Preview
Screenshots of some of the more significant changes:
Contributing > Writing Documentation Pages
Details
@ember-data/json-api
Includes detailed overview of the {json:api} package with setup and configuration guidance.
Details
@ember-data/model
Enriched with model definition patterns and usage examples.
Details
@ember-data/serializer
Enhanced with sections on legacy serializers, implementation patterns, and usage examples.
Details
@ember-data/store
Package overview now includes comprehensive introduction, installation instructions, and usage examples.
Details
@ember-data/tracking
Improved with reactive tracking overview and integration details.
Details
@warp-drive/build-config
Added comprehensive build configuration documentation.
Details
Impact