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 <[email protected]>
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 <[email protected]>
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 <[email protected]>
…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 <[email protected]>
✅ 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.
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