f5535c9d5c
Hugo-native templates for API reference documentation. Operations render as server-side HTML instead of client-side Redoc, providing faster page loads, full SEO indexability, and consistent styling. Architecture: - Tag-based navigation: operations grouped by OpenAPI tag, accessed via tag pages only (no individual operation URLs) - Generation script auto-discovers products from .config.yml files, deriving Hugo paths and menu keys from directory structure - Per-tag JSON/YAML chunks for fast Hugo template rendering - Inline curl examples generated from OpenAPI specs at build time Templates (layouts/api/, layouts/partials/api/): - tag-renderer.html: renders all operations for a tag - operation.html: individual operation with parameters, request body, responses, and schema rendering - code-sample.html: curl examples with Ask AI integration - section-children.html: tag listing on section index pages - all-endpoints-list.html: all operations sorted by path Generation (api-docs/scripts/generate-openapi-articles.ts): - Auto-discovery from .config.yml replaces hardcoded productConfigs - Each API section generates independently (no cross-spec merging) - Frontmatter-driven template data (specDownloadPath, articleDataKey) - Link transformation: /influxdb/version/ placeholders resolved to product-specific paths Removed: - Redoc renderer, JavaScript components, and CSS - Shadow DOM test infrastructure (~160 lines) - Operation page generation (dead generatePathPages function) - mergeArticleData() and slugifyDisplayName() Styles (assets/styles/layouts/_api-*.scss): - 3-column layout: sidebar, content, sticky TOC - Theme-aware code blocks for curl examples - Method badges (GET/POST/PUT/DELETE) with color coding - Collapsible schema sections with depth tracking Tests (cypress/e2e/content/api-reference.cy.js): - Tag page rendering with operation structure - Download button verification per section - All-endpoints page with operation cards - Related links from x-related OpenAPI extension - Code sample and Ask AI link validation |
||
|---|---|---|
| .. | ||
| cloud-serverless | ||
| common | ||
| influxdb3-distributed | ||
| influxdb3-plugins | ||
| label-migration | ||
| README.md | ||
| build-agent-instructions.js | ||
| migrate-api-links.cjs | ||
README.md
InfluxData Documentation Helper Scripts
This directory contains scripts to assist with InfluxDB documentation workflows, including release notes generation, CLI/API documentation auditing, and version management.
Directory Structure
helper-scripts/
├── common/ # Shared scripts used across all products
├── influxdb3-monolith/ # Scripts for InfluxDB 3 Core & Enterprise
├── influxdb3-distributed/ # Scripts for InfluxDB 3 Clustered & Cloud Dedicated
├── cloud-serverless/ # Scripts for InfluxDB Cloud Serverless
└── output/ # Generated outputs from all scripts
Product Categories
InfluxDB 3 Monolith
- Products: InfluxDB 3 Core, InfluxDB 3 Enterprise
- Deployment: Single binary deployment
- Scripts Location:
influxdb3-monolith/
InfluxDB 3 Distributed
- Products: InfluxDB 3 Clustered, InfluxDB 3 Cloud Dedicated
- Deployment: Distributed/Kubernetes deployment
- Scripts Location:
influxdb3-distributed/
Cloud Serverless
- Product: InfluxDB Cloud Serverless
- Deployment: Fully managed cloud service
- Scripts Location:
cloud-serverless/
Common Scripts
Release Notes Generation
Release notes are generated using the unified docs CLI. See scripts/docs-cli/README.md for full documentation.
Usage:
# Using product keys (resolves paths from config)
npx docs release-notes v3.1.0 v3.2.0 --products influxdb3_core,influxdb3_enterprise
# Using direct repository paths
npx docs release-notes v3.1.0 v3.2.0 --repos ~/repos/influxdb,~/repos/enterprise
common/update-product-version.sh
Updates product version numbers in data/products.yml and related documentation files.
Usage:
./common/update-product-version.sh --product <product> --version <version>
Example:
./common/update-product-version.sh --product core --version 3.2.1
Product-Specific Scripts
InfluxDB 3 Monolith (Core & Enterprise)
See influxdb3-monolith/README.md for detailed documentation.
Key Scripts:
audit-cli-documentation.sh- Audits CLI commands against existing documentationsetup-auth-tokens.sh- Sets up authentication tokens for local containers
InfluxDB 3 Distributed (Clustered & Cloud Dedicated)
See influxdb3-distributed/README.md for detailed documentation.
Key Scripts:
clustered-release-artifacts.sh- Downloads release artifacts for Clustered releases
Output Directory
All scripts write their outputs to organized subdirectories:
output/
├── release-notes/ # Generated release notes
├── cli-audit/ # CLI documentation audit reports
├── api-audit/ # API documentation audit reports
└── artifacts/ # Downloaded release artifacts
GitHub Workflow Integration
These scripts are integrated with GitHub Actions workflows:
- Workflow:
.github/workflows/prepare-release.yml - Uses:
docs release-notes(unified CLI),update-product-version.sh
Quick Start
-
Clone the repository
git clone https://github.com/influxdata/docs-v2.git cd docs-v2/helper-scripts -
Make scripts executable
find . -name "*.sh" -type f -exec chmod +x {} \; -
Run a script
# Generate release notes (using unified CLI) npx docs release-notes v3.1.0 v3.2.0 --products influxdb3_core,influxdb3_enterprise # Audit CLI documentation npx docs audit main --products influxdb3_core
Contributing
When adding new scripts:
- Place in the appropriate product directory
- Follow naming conventions (lowercase with hyphens)
- Include comprehensive help text and documentation
- Update the relevant README files
- Test with all applicable products
- Ensure outputs go to the
output/directory
Archived Scripts
Deprecated scripts are moved to archive/ subdirectories. These scripts are kept for reference but should not be used in active workflows.