-
Notifications
You must be signed in to change notification settings - Fork 320
Feat api uplift #6622
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: master
Are you sure you want to change the base?
Feat api uplift #6622
Conversation
Replace legacy API documentation approach with modern Scalar-based rendering:
## Architecture Changes
- Add renderer abstraction (`layouts/partials/api/`) supporting Scalar and RapiDoc
- Create `api` layout type for API reference pages (single.html, list.html)
- Configure renderer via `site.Params.apiRenderer` (default: scalar)
## OpenAPI Processing Pipeline (TypeScript)
- `api-docs/scripts/generate-openapi-articles.ts` - Main generation script
- `api-docs/scripts/openapi-paths-to-hugo-data/` - OpenAPI to Hugo data converter
- Generates per-endpoint path fragments for AI agent access
- Creates Hugo content pages with `type: api` frontmatter
## AI Agent Accessibility
- Full specs at `/openapi/influxdb-{product}.yml` and `.json`
- Per-endpoint fragments at `/openapi/influxdb-{product}/paths/`
- `<link rel="alternate">` tags in HTML for machine discovery
## Scalar Features
- Dark/light theme support synchronized with site theme
- InfluxData brand colors
- Responsive layout
- Download link for OpenAPI spec
## Products Supported
- cloud-v2, oss-v2
- influxdb3-core, influxdb3-enterprise
- cloud-dedicated, cloud-serverless, clustered
Usage: node api-docs/scripts/dist/generate-openapi-articles.js [product]
- latest-patch.html: Replace deprecated .Store with local variable assignment. The .Store method was removed from shortcode context in newer Hugo versions. - api-endpoint.html: Add nil check for productRef lookup to prevent index errors when productKey is not in productAliases dictionary. Falls back to "influxdb" as default product reference.
- yarn build:api-docs: Generate API docs for all products - yarn build:api-docs cloud-v2: Generate for specific product - yarn build:api-docs:compile: Recompile TypeScript if modified
…. Split ui-dev subagent into hugo-, ts-, and testing-specific agents.
- Add CSS for operations list cards with method badges, paths, and summaries - Remove duplicate Overview section from list.html (was duplicating summary) - Split "Data Operations" into separate nav groups: Write data, Query data, Cache data
- Add support for tag-based article generation with operations metadata - Generate articles.yml data files with tag, menuName, and isConceptual fields - Include operations array in frontmatter for tag pages
- Rewrite single.html for operation pages with RapiDoc integration - Simplify rapidoc.html partial for tag-based rendering - Add sidebar-nav include to sidebar.html for API navigation - Add tab-panels.html and tabs.html for content organization
- Add api-nav.ts for sidebar navigation collapse/expand - Add api-scalar.ts for Scalar API renderer integration - Add api-tabs.ts for tab switching functionality - Add api-toc.ts for table of contents generation - Register components in main.js
- Add YAML article data files for all InfluxDB products - Add sidebar-nav.html partial for API navigation rendering - Rename data directory from article-data to article_data for Hugo compatibility - Remove obsolete JSON articles file
- Update hugo.yml config for API docs settings - Simplify _api-overrides.scss (removed hardcoded content styles) - Import _api-layout.scss in styles-default.scss - Update API landing pages for Core and Enterprise with redirects - Update OpenAPI spec files - Update dependencies
- Update tests for new tag-based API page structure - Add tests for operations list rendering - Add tests for sidebar navigation groups
…tion - Header summary now shows only the first sentence from description using regex extraction with fallback to first line for descriptions without sentence-ending punctuation - Added Overview section with full description after endpoints list
- Sidebar nav now shows operations with method badges and paths instead of duplicating tag names when groups are expanded - Added background color to nav group items to match sidebar - Increased max-height for expanded groups to accommodate all operations - Added styles for operation items in sidebar nav (.api-nav-operation) - Fixed summary paragraph width by setting flex-basis to 100%
- Changed operation link font-size from 0.85rem to 0.95rem to match sidebar - Changed path code font-size from 0.75rem to 0.85rem for consistency - Adjusted method badge font-size from 0.55rem to 0.6rem for readability
…size - Add button reset styles to .api-nav-group-header for dark mode compatibility (background: none, border: none, width: 100%) - Increase operation link font-size from 0.95rem to 1rem to match sidebar nav-item font size (18px base) - Increase api-path code font-size from 0.85rem to 0.9rem
Add API nav items as children of "InfluxDB HTTP API" menu item: - New api-menu-items.html partial generates nav from data/articles.yml - Modified nested-menu.html to inject API nav for API parent menu item - Updated api_nav_groups.yml to add url for Administration group - Created Administration landing pages for Core and Enterprise - Updated .gitignore to allow hand-crafted API conceptual pages The Administration page uses layout: list and isConceptual: true to render content directly without RapiDoc wrapper.
Now that API navigation is integrated into Hugo's menu system: - Remove api-nav.ts component (no longer needed) - Remove api/sidebar-nav.html partial (replaced by api-menu-items.html) - Remove api-nav component registration from main.js - Update sidebar.html to pass siteData to nested-menu for API nav - Fix anchor ID handling for special characters (like / in operation IDs)
Remove multi-tag groups (Administration, Concepts) and flatten to single-tag groups for direct linking. Each API tag now renders as a direct nav item instead of being nested under a parent group. - Update api_nav_groups.yml to use single-tag groups only - Delete Administration landing pages (not needed without nesting) - Improve SCSS styling for API nav visibility and active states
Add visual badges to distinguish v1-compatible and v2-compatible API endpoints in the sidebar navigation. This helps users migrating from InfluxDB v1 or v2 quickly identify which compatibility layer each endpoint belongs to. Changes: - Add x-compatibility-version extension to compatibility operations - Add externalDocs links to reduce verbose descriptions in specs - Update generator to extract compatVersion and externalDocs fields - Display colored badges (purple for v1, cyan for v2) in sidebar nav - Strip redundant "(v1-compatible)" text when badge is shown - Add hover tooltips explaining compatibility context
The feature is shippable, but needs a few small fixes and we'll need to update or alias all API docs links for Core and Ent3. - Add rapidoc-mini.ts TypeScript component with CDN loading and theme sync - Add api-operation layout for standalone operation pages - Add rapidoc-mini.html partial for reusable RapiDoc rendering - Add rapidoc-custom.css for RapiDoc style overrides - Register rapidoc-mini component in main.js - Add article data for cloud-dedicated and clustered products - Update API reference Cypress tests
…uality - Restore original RapiDoc match-paths format (method /path) for proper filtering - Restrict operation tags to primary tag in tag-specific specs to prevent duplicates - Rename Token tag to Auth token for clarity in Core and Enterprise specs - Remove Table tag from cache operations (distinct_cache, last_cache) - Add build script combining API docs, Hugo, and Markdown generation - Skip summary rendering for conceptual pages - Add isConceptual check to hide operations in nav for conceptual pages
- Update api_nav_groups.yml to use "Auth token" instead of "Token" - Remove x-tagGroups from Core and Enterprise specs (Redoc-specific, not needed for RapiDoc) - Add migration notes to plan document for future product migrations
…habetically - Remove api_nav_groups.yml config file (no longer needed) - Update api-menu-items.html to derive order from article data - Sort: conceptual tags (traitTags) first, then other tags alphabetically - Reduces template from 255 to 152 lines
- Add api/section-children.html partial for API section index pages
- Update api/list.html to detect section index vs tag pages
- Add "All endpoints" nav item listing all operations sorted by method+path
- Remove {{< children >}} shortcode from API index pages (use data-driven list)
Increase font size from 0.55rem to 0.9rem for better readability while keeping the standard sans font for space efficiency.
Code reviewFound 1 issue:
docs-v2/layouts/partials/api/rapidoc.html Lines 95 to 110 in 90044bd
🤖 Generated with Claude Code - If this code review was useful, please react with 👍. Otherwise, react with 👎. |
Extract inline JavaScript from rapidoc.html into a proper TypeScript component following the established component pattern.
Remove ~230 lines of inline JavaScript and use the new api-rapidoc TypeScript component via data-component attribute instead.
Remove unused Scalar API documentation renderer: - Delete layouts/partials/api/scalar.html - Delete assets/js/components/api-scalar.ts - Simplify renderer.html to only use RapiDoc - Remove ApiScalar from main.js component registry - Remove apiRenderer config option from hugo.yml
Remove unused tabs component and partials: - Delete assets/js/components/api-tabs.ts - Delete layouts/partials/api/tabs.html - Delete layouts/partials/api/tab-panels.html - Remove ApiTabs from main.js component registry The new architecture renders content directly without tabs.
Remove tests for tabs and 3-column layout that no longer exist. Keep basic API reference tests and RapiDoc Mini component tests.
API reference uplift:
Latest screenshot:
