History

Jason Stirnaman 20562d5bb6 Automate plugin documentation sync workflow between influxdb3_plugins and docs-v2 (#6329 ) * feat(plugins): add automated plugin documentation sync workflow - Add GitHub Actions workflow for syncing plugin docs from influxdb3_plugins - Create issue template for triggering sync requests - Add Node.js transformation script (port_to_docs.js) with ES modules - Add mapping configuration (docs_mapping.yaml) for all official plugins - Add npm scripts for plugin sync operations - Include comprehensive documentation in helper-scripts/influxdb3-plugins/README.md The workflow provides: - Issue-triggered automation with no cross-repo secrets required - Validation of source READMEs against template requirements - Content transformation with Hugo shortcodes and GitHub URLs - Screenshot generation for visual validation - Automatic PR creation with detailed change summaries * Updated source paths in docs_mapping.yaml to use ./influxdb3_plugins/ instead of ../influxdb3_plugins/ to match what the GitHub Actions workflow expects when it clones the repository: 1. GitHub Actions workflow clones to ./influxdb3_plugins/ 2. docs_mapping.yaml references ./influxdb3_plugins/influxdata/[plugin]/README.md 3. Local development can manually clone the repo to the same location for testing Tupdated all the source paths in docs_mapping.yaml to use ./influxdb3_plugins/ instead of ../influxdb3_plugins/. This now matches exactly what the GitHub Actions workflow expects when it clones the repository. The paths are now consistent: 1. GitHub Actions workflow clones to ./influxdb3_plugins/ 2. docs_mapping.yaml references ./influxdb3_plugins/influxdata/[plugin]/README.md 3. Local development can manually clone the repo to the same location for testing This resolves the inconsistency and makes the automation more reliable. For local development, developers would just need to run: git clone https://github.com/influxdata/influxdb3_plugins.git From the docs-v2 root directory, and then they can use the same paths that the automation uses. * Updated source paths in docs_mapping.yaml to use ./influxdb3_plugins/ instead of ../influxdb3_plugins/ to match what the GitHub Actions workflow expects when it clones the repository: 1. GitHub Actions workflow clones to ./influxdb3_plugins/ 2. docs_mapping.yaml references ./influxdb3_plugins/influxdata/[plugin]/README.md 3. Local development can manually clone the repo to the same location for testing Tupdated all the source paths in docs_mapping.yaml to use ./influxdb3_plugins/ instead of ../influxdb3_plugins/. This now matches exactly what the GitHub Actions workflow expects when it clones the repository. The paths are now consistent: 1. GitHub Actions workflow clones to ./influxdb3_plugins/ 2. docs_mapping.yaml references ./influxdb3_plugins/influxdata/[plugin]/README.md 3. Local development can manually clone the repo to the same location for testing This resolves the inconsistency and makes the automation more reliable. For local development, developers would just need to run: git clone https://github.com/influxdata/influxdb3_plugins.git From the docs-v2 root directory, and then they can use the same paths that the automation uses. * Jmercer/plugin sync test (#6468) * fix: update workflow branch references from master to main * fix: update issue template branch references from master to main - Update sync-plugin-docs.yml description (line 40) - Update placeholder from 'master' to 'main' (line 41) - Update default value from 'master' to 'main' (line 42) - Add influxdb3_plugins/ to .gitignore - Ensures template matches influxdb3_plugins default branch * Update .gitignore --------- Co-authored-by: Jason Stirnaman <stirnamanj@gmail.com> * Update docs_mapping.yaml * Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Apply suggestion from @jstirnaman * Apply suggestion from @jstirnaman * Apply suggestion from @jstirnaman * Apply suggestion from @jstirnaman * Use <docs-root>/.ext/influxdb3_plugins for the source path --------- Co-authored-by: Jameelah Mercer <36314199+MeelahMe@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>		2025-10-20 17:18:34 -05:00
..
cloud-serverless	chore(ci): Automation scripts to compare influxdb3 CLI help to reference documentation and generate an audit report, runs influxdb3 core and enterprise using Docker, improves compose.yaml, restructures helper-scripts for different versions	2025-07-07 12:13:36 -05:00
common	Updated all README files in the	2025-07-07 12:45:48 -05:00
influxdb3-distributed	chore(ci): Automation scripts to compare influxdb3 CLI help to reference documentation and generate an audit report, runs influxdb3 core and enterprise using Docker, improves compose.yaml, restructures helper-scripts for different versions	2025-07-07 12:13:36 -05:00
influxdb3-plugins	Automate plugin documentation sync workflow between influxdb3_plugins and docs-v2 (#6329 )	2025-10-20 17:18:34 -05:00
README.md	Updated all README files in the	2025-07-07 12:45:48 -05:00
build-agent-instructions.js	chore(js): formatting	2025-10-08 16:51:25 -05:00

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

`common/generate-release-notes.js`

JavaScript ESM script that generates release notes by analyzing git commits across multiple repositories. Supports flexible configuration for different InfluxDB products and output formats.

Usage:

node common/generate-release-notes.js [options] <from_version> <to_version> [repo_paths...]

Options:

--config <file> - Load configuration from JSON file
--format <type> - Output format: 'integrated' or 'separated'
--no-fetch - Skip fetching latest commits from remote
--pull - Pull latest changes (use with caution)
--no-pr-links - Omit PR links from commit messages

Examples:

# Using configuration file (recommended)
node common/generate-release-notes.js --config common/config/influxdb3-core-enterprise.json v3.1.0 v3.2.0

# Traditional command-line arguments
node common/generate-release-notes.js v3.1.0 v3.2.0 ~/repos/influxdb ~/repos/influxdb_pro

`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 documentation
setup-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: generate-release-notes.js, 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
node common/generate-release-notes.js --config common/config/influxdb3-core-enterprise.json v3.1.0 v3.2.0

# Audit CLI documentation
node influxdb3-monolith/audit-cli-documentation.js core local

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.