CLI Docs: Automated reference documentation system #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 failed. Why did it fail? →
|
- 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>
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.
Overview
Completes the CLI documentation automation system with production-ready reference documentation, navigation integration, and automated update workflow.
What's New
Documentation
commands-reference.md) - Categorized command index with quick reference, replaces legacycommands.mdAutomation
Maintenance
/cli/commandsURLsFile Changes
Impact
✅ All 18 CLI command groups discoverable via navigation
✅ Legacy URLs redirect to new command reference
✅ Automated updates on CLI releases
✅ Version compatibility clearly indicated
✅ Single source of truth maintained
✅ Production-ready deployment
Testing
What's Next
Deploy to production and test the automation with the next CLI release.
@netlify /platform-cloud/cli/commands-reference