Extract CLI docs to standalone docset, add release-triggered automation #1013
Conversation
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
Implements automated CLI reference documentation generation using the overlay pattern: - Scripts to generate docs from tower-cli metadata - GitHub Actions workflows for automated updates on CLI releases - Directory structure for overlays (manual content) and reference (auto-generated) - Sample overlay templates for main commands and subcommands Structure: - cli/scripts/: Python scripts for doc generation and comparison - cli/overlays/: Manual examples and guides (merged with generated docs) - cli/reference/: Auto-generated command reference (one file per main command) - cli/metadata/: Versioned CLI metadata snapshots - .github/workflows/: Automation workflows (dispatch and scheduled check) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Updates: - Use hierarchy field from metadata (pre-built command tree) - Handle both 'children' and 'subcommands' fields - Filter out string class name references - Add overlay support for standalone commands - Fix sample overlay to match actual CLI structure (tw launch, not tw pipelines launch) - Add .gitignore for large metadata files Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Auto-generated documentation for 18 CLI commands from tower-cli metadata. Includes manual overlay content for pipelines and launch commands. Structure: - One markdown file per main command - All subcommands included as sections within each file - Manual examples and guides merged from overlays/ Commands documented: actions, collaborators, compute-envs, credentials, data-links, datasets, info, labels, launch, members, organizations, participants, pipelines, runs, secrets, studios, teams, workspaces Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
…ce docs Major improvements: - Created extract-overlays.py script to extract 77 overlay files from existing commands.md - Extracted overlays preserve rich content: examples with output, admonitions, cross-references, "This command will:" sections - Updated generate-cli-docs.py to support better overlay matching (both .md and -examples.md patterns) - Created fix-reference-docs.py to add periods to descriptions and fix relative links - Removed Synopsis headings from generated docs for cleaner format Generated reference docs now include: ✓ Real command examples with actual output ✓ Contextual explanations and prerequisites ✓ Admonitions (:::note, :::tip) with platform-specific guidance ✓ Cross-references to other documentation pages ✓ "This command will:" explanatory sections for complex commands ✓ Help command references ✓ Run state explanations and workflows Total: 3,433 lines of rich documentation across 18 command reference pages Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
✅ Deploy Preview for seqera-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
- Add Command Reference landing page with navigation structure - Integrate 18 reference pages into Cloud and Enterprise sidebars - Update GitHub Actions workflow to inject CLI version info - Add redirects for legacy /cli/commands URLs - Clean up temporary files and outdated scripts - Document single source of truth strategy - Update maintenance documentation Changes: - New: commands-reference.md landing page (Cloud & Enterprise) - New: Complete reference navigation in both sidebars - New: Automated CLI version notices in docs - New: Comprehensive maintenance guides (README.md, MAINTENANCE.md) - Updated: GitHub Actions workflow with correct paths and version injection - Updated: Redirects for backward compatibility - Deleted: 99 temporary/development files - Deleted: Legacy commands.md (replaced by commands-reference.md) Ready for production deployment.
MDX was evaluating ${} as JavaScript template literals, breaking the build.
Changes:
- Remove ${} wrappers from environment variables (TOWER_WORKSPACE_ID)
- Replace ${COMPLETION-CANDIDATES} with actual status values:
- launch.md: SUBMITTED, RUNNING, SUCCEEDED, FAILED, CANCELLED
- pipelines.md: OWNER, MEMBER, COLLABORATOR
- studios.md: STARTING, RUNNING, STOPPED, STOPPING
Fixes Netlify deployment errors and local dev server issues.
llewellyn-sl
commented
Jan 22, 2026
Signed-off-by: Llewellyn vd Berg <113503285+llewellyn-sl@users.noreply.github.com>
llewellyn-sl
commented
Jan 22, 2026
llewellyn-sl
commented
Jan 22, 2026
llewellyn-sl
commented
Jan 22, 2026
llewellyn-sl
commented
Jan 22, 2026
llewellyn-sl
commented
Jan 22, 2026
Signed-off-by: Llewellyn vd Berg <113503285+llewellyn-sl@users.noreply.github.com>
Signed-off-by: Llewellyn vd Berg <113503285+llewellyn-sl@users.noreply.github.com>
- Added Option 1 and Option 2 headings for installation methods - Added Homebrew tap installation instructions (brew install seqeralabs/tap/tw) - Updated last updated date to 2025-08-18 - Minor text cleanup (removed "your" from "your Seqera Platform instance") - Applied changes to: - platform-cloud CLI docs - platform-enterprise CLI docs - Versioned enterprise docs (25.1, 25.2, 25.3) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Added get_hierarchy() to support both old and new metadata formats
- Old: { "tw": {...} }
- New: { "metadata": {...}, "hierarchy": {...} }
- Updated count_commands() and get_all_commands() to handle 'children' field
- Added metadata version display in comparison reports
- Filters out string entries in subcommands/children arrays
- Added comprehensive compatibility analysis document
The new metadata format from tower-cli (ll-cli-docs-automation-infrastructure
branch) adds a metadata wrapper and uses 'children' instead of 'subcommands'.
This change ensures backward compatibility while supporting the enhanced format.
Tested with actual metadata from tower-cli branch - successfully processes
164 commands with new format structure.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
BREAKING: The metadata extraction now uses the Java-based CliMetadataExtractor from tower-cli instead of the Python script. Changes to workflow (.github/workflows/update-cli-docs.yml): - Added Java 17 setup step for running Gradle - Updated metadata extraction to use `./gradlew extractCliMetadata` - Simplified extraction process (no longer needs Python for extraction) - Copies output from tower-cli/docs/cli-metadata.json Changes to documentation: - Updated README.md with new extraction method and troubleshooting - Updated MAINTENANCE.md with manual update process using Gradle - Replaced references to Python script with Java extractor details The new Java extractor: - Uses reflection to analyze picocli annotations (deterministic) - Outputs enhanced metadata format with version and timestamps - Lives at: src/main/java/io/seqera/tower/cli/utils/metadata/CliMetadataExtractor.java - Invoked via Gradle task: ./gradlew extractCliMetadata Compatibility: All downstream scripts (generate-cli-docs.py, compare-metadata.py) already updated to handle the new metadata format structure. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Documents all changes made to integrate Java metadata extractor: - Workflow modifications (Java setup, Gradle task usage) - Documentation updates (README, MAINTENANCE) - Compatibility verification - Testing results - Next steps and references Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Successfully tested the entire update-cli-docs.yml workflow locally: Test Results: - ✅ Java extractor (./gradlew extractCliMetadata) works correctly - ✅ Extracts 164 commands, 1011 options in new metadata format - ✅ compare-metadata.py handles new format (displays version & timestamp) - ✅ generate-cli-docs.py creates 19 complete markdown files - ✅ All overlays merge correctly - ✅ Output files properly formatted with frontmatter - ✅ Complete workflow executes in ~11s (excluding clone) Test Environment: - Java 17 (OpenJDK 17.0.13) - Python 3.14 - Tower-CLI infrastructure branch (has Java extractor) Test Artifacts: - Extracted metadata: 975 KB JSON with complete hierarchy - Generated docs: 19 files, 144 KB total, all with valid content - Sample output: credentials.md (553 lines, properly formatted) Note: Tested with development branch since release tags don't have the Java extractor yet. Workflow is production-ready for when tower-cli publishes a release with the extractor. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit extracts CLI documentation from platform-cloud and platform-enterprise into a new standalone docset at /platform-cli, creating a single source of truth for CLI documentation across all Platform versions. ## Major Changes ### New Standalone Docset Structure - Created platform-cli-docs/ with docs/, overlays/, scripts/, and metadata/ - New sidebar at platform-cli-docs/docs/sidebar/sidebar.js - CLI docs now render at /platform-cli route - Added "Platform CLI" to main navbar ### Documentation Updates - Moved all CLI content from platform-cloud/docs/cli/ to platform-cli-docs/ - Updated all relative links to absolute /platform-cloud/ paths - Fixed reference-style link definitions in overlays - Removed code formatting from all command headers (e.g., \`tw credentials\` → tw credentials) - Updated homepage link to point to /platform-cli ### Sidebar Updates - platform-cloud/cloud-sidebar.json: Replaced CLI category with external link - platform-enterprise_docs/enterprise-sidebar.json: Replaced CLI category with external link - Updated 7 versioned sidebars (23.3, 23.4, 24.1, 24.2, 25.1, 25.2, 25.3) with external links - Versions without CLI sections (22.4, 23.1, 23.2) left unchanged ### Automation Updates - Updated .github/workflows/update-cli-docs.yml with all new paths - Removed "Copy to enterprise docs" step (no longer needed) - Updated scripts/README.md and scripts/MAINTENANCE.md with new strategy - All workflow paths now reference platform-cli-docs/ ### Cleanup - Removed platform-cloud/docs/cli/ - Removed platform-enterprise_docs/cli/ - Removed all versioned CLI directories (platform-enterprise_versioned_docs/version-*/cli/) ### URL Redirects - Added redirects in static/_redirects for all old CLI URLs - /platform-cloud/cli/* → /platform-cli (301) - /platform-enterprise/cli/* → /platform-cli (301) - /platform-enterprise/:version/cli/* → /platform-cli (301) ### Configuration - Added docs_platform_cli plugin to docusaurus.config.js - Registered plugin with EXCLUDE_PLATFORM_CLI environment variable support - Added navbar item for Platform CLI ## Benefits - Single source of truth eliminates duplication and sync issues - CLI versioning independent from Platform versioning - Simplified maintenance with one documentation location - Clean URL structure (/platform-cli) consistent with /platform-api - Backward compatibility via redirects for all old URLs Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
llewellyn-sl
changed the title
Contributor
Author
|
@netlify /platform-cli/overview |
Contributor
Author
|
Correct deployment preview link here |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
CLI Documentation: Standalone Docset + Automation System
This PR implements two major improvements to CLI documentation:
/platform-cli🎯 Standalone Docset Extraction
New Structure
platform-cli-docs/with complete CLI documentation/platform-cli(consistent with/platform-api)Migration Details
platform-cloud/docs/cli/toplatform-cli-docs//platform-cloud/pathsSidebar Updates
Cleanup
platform-cloud/docs/cli/platform-enterprise_docs/cli/🤖 Automated Documentation System
GitHub Actions Workflow
File:
.github/workflows/update-cli-docs.ymlTriggers:
Process:
Key Features
platform-cli-docs/Documentation
platform-cli-docs/scripts/README.md- Workflow overviewplatform-cli-docs/scripts/MAINTENANCE.md- Maintenance guideplatform-cli-docs/scripts/generate-cli-docs.py- Generation scriptplatform-cli-docs/scripts/compare-metadata.py- Version comparison📊 Impact
Before
After
/platform-cli🔍 Testing
Local validation:
/platform-cliFiles changed: 190 files (+1,441, -14,516)
🎉 Benefits
/platform-apipattern📝 Related Work
🤖 Generated with Claude Code
@netlify /platform-cli/overview