[Draft] API Documentation Updates for v1.102.0 #1039
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
- New base spec: seqera-api-1.102.0.yaml - Comparison overlay generated - Analysis report created - Claude-generated overlays ready for review
✅ Deploy Preview for seqera-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
This was referenced Jan 20, 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>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Contributor
Author
There was a problem hiding this comment.
🪄 Pre-commit formatting suggestions
You can apply each suggestion via the GitHub UI, add a comment containing the keyword fix formatting or set up pre-commit locally and commit again.
platform-api-docs/scripts/overlay_archives/base-1.95-to-1.102.0-changes-analysis.json
Show resolved
Hide resolved
- Add workflows-operations-overlay with instructions for resuming workflows - Add manual-field-descriptions-overlay with 11 missing API field descriptions Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Signed-off-by: Llewellyn vd Berg <113503285+llewellyn-sl@users.noreply.github.com>
Contributor
llewellyn-sl
left a comment
llewellyn-sl
left a comment
There was a problem hiding this comment.
Overlay review complete. Adding overlays approved label to trigger docs regeneration workflow.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
llewellyn-sl
added
the
overlays-approved
…spec Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
llewellyn-sl
added
overlays-approved
llewellyn-sl
removed
the
overlays-approved
- Add critical rule: NEVER create overlay files with empty actions lists - Add to common mistakes: Empty overlays break workflow automation - Remove empty data-links-schemas-overlay-1.102.0.yaml from overlays doc Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
llewellyn-sl
added
the
overlays-approved
- Changed pattern from [^`]+ to .*? with proper boundaries - Use findall and take last match for closest filename - Fixes extraction failing when overlay content contains backticks Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- List extracted overlay files before consolidation - Count overlays being consolidated - Show first 30 lines of consolidated file - Count total action items in consolidated overlay - Upload all overlay files as artifacts on failure for inspection Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Workflow fixes: - Fix version detection to exclude decorated spec and sort by semantic version - Fix consolidation to find overlay files with correct version number - Fix cleanup to sort base specs by version (not modification time) - Add debugging output and artifact upload on failure Script fixes: - Update extract-api-tables.mjs to check for both .yaml and .yml - Update docusaurus.config.js to use .yaml extension This fixes the critical bug where version detection picked up "latest-decorated" instead of "1.102.0", causing consolidation to look for non-existent overlay files. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Capture validation output to file to avoid overwhelming logs - Count errors, warnings, and hints separately - Only fail if actual ERROR-level issues are found - Continue if only hints/warnings (like missing examples) - Show summary of issue counts instead of full output This prevents the workflow from failing due to INFO-level hints about missing examples, which are non-critical. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Documents all fixes made to the overlay workflow and current issue: - Fixed empty overlay file issue - Fixed regex handling backticks - Fixed version detection - Fixed .yaml/.yml handling - Made validation less verbose - Current issue: Parameter removal actions not in generated overlays This allows continuing troubleshooting in a new context window. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Applied "remove first, then update" pattern to fix all validation errors:
1. Parameter duplicate errors (4 → 0)
- Added parameter array removal actions in data-links-parameters overlay
- Remove entire array before replacing with enriched descriptions
2. Deprecated endpoint error (1 → 0)
- Added removal action for /data-links/{dataLinkId}/download endpoint
3. Duplicate required fields (12 → 0)
- Created fix-duplicate-required-fields overlay
- Remove existing required field, then add correct values
- Fixed 12 compute config schemas
Updated openapi-overlay-generator SKILL.md with critical instructions:
- Preserve ALL actions from comparison overlay
- Parameter array replacement pattern
- Required field replacement pattern
Total: 10 overlays, 177 actions, 0 validation errors
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
…filename Fixes validation error: "component #/components/schemas/LocalComputeConfig does not exist" Changes: - Added add-missing-schema-overlay-1.102.0.yaml to add LocalComputeConfig schema that was accidentally excluded from v1.95 decorated spec - Fixed add-identities-tag filename to match extraction regex (*-overlay-*.yaml) - Placed missing schema overlay first to ensure it's added before being referenced Local validation: 0 errors, 1 informational warning Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Add submodules: recursive to checkout step to ensure multiqc_docs/multiqc_repo and other submodules are properly initialized before running docusaurus commands. Fixes error: "The docs folder does not exist for version current" Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Fixes workflow failures: 1. "No url found for submodule path 'platform-repo'" 2. "The docs folder does not exist for version current" Changes: - Remove broken platform-repo submodule entry (it's checked out fresh in workflows, not a submodule) - Remove submodules: recursive from checkout (no real submodules exist) - Add EXCLUDE_MULTIQC=true to docusaurus steps (multiqc_repo is gitignored and not available in CI) The generate-openapi-overlays workflow already checks out platform-repo as a fresh clone, not a submodule. The apply-overlays workflow doesn't need multiqc docs. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Add EXCLUDE_* env vars to docusaurus steps to only process Platform OpenAPI docs: - EXCLUDE_CHANGELOG: true - EXCLUDE_PLATFORM_ENTERPRISE: true - EXCLUDE_PLATFORM_CLOUD: true - EXCLUDE_PLATFORM_API: true - EXCLUDE_MULTIQC: true - EXCLUDE_FUSION: true - EXCLUDE_WAVE: true Benefits: - Faster builds (only processes relevant docset) - Less fragile (doesn't require other docs dependencies) - Clearer intent (workflow only updates API reference docs) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Instead of using EXCLUDE_* flags with 'all', directly target the 'platform' OpenAPI spec ID to avoid plugin dependency issues. Changes: - clean-api-docs all → clean-api-docs platform - gen-api-docs all → gen-api-docs platform - Removed all EXCLUDE_* env vars (not needed when targeting specific spec) This fixes "Cannot read properties of null" error that occurred when excluding all docs plugins while OpenAPI plugin still tried to find them. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Even when targeting specific 'platform' spec, docusaurus initializes all plugins from config. Need to exclude plugins that depend on gitignored repos: - EXCLUDE_MULTIQC: true (multiqc_docs/multiqc_repo is gitignored) - EXCLUDE_FUSION: true (fusion_docs/fusion_repo is gitignored) - EXCLUDE_WAVE: true (wave_docs/wave_repo is gitignored) Platform docs plugins can remain enabled since those directories exist in repo. Fixes: "The docs folder does not exist for version current at multiqc_docs/multiqc_repo/docs/markdown" Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
The OpenAPI plugin has dependencies on other docs plugins. When targeting just 'platform', it breaks the plugin initialization chain. Solution: Use 'all' but exclude only the OSS repo plugins that need gitignored directories: - EXCLUDE_MULTIQC: true - EXCLUDE_FUSION: true - EXCLUDE_WAVE: true Keep Platform docs plugins enabled (enterprise, cloud, api, openapi) since those directories exist in the repo and may be dependencies for OpenAPI plugin. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Root cause: OpenAPI plugin configured with docsPluginId: "classic" but
preset-classic had docs: false, so no classic docs plugin existed.
This caused: "Cannot read properties of null (reading '0')" error when
the OpenAPI plugin tried to find the classic docs plugin instance.
Changes:
1. Enable classic docs plugin in preset-classic config:
- docs: false → docs: { path: "platform-api-docs/docs", routeBasePath: "/" }
- Points to where OpenAPI plugin generates docs
2. Back to targeting 'platform' spec specifically (with EXCLUDE flags for OSS repos)
Now the OpenAPI plugin has the "classic" docsPluginId it needs to function.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Added comprehensive documentation of all workflow failures and fixes: - Broken platform-repo submodule removal - OSS repo plugin exclusions (multiqc, fusion, wave) - Classic docs plugin enablement for OpenAPI plugin dependency - All 8 commits from troubleshooting session - Key learnings about git submodules, docusaurus plugins, and CI dependencies Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
The OpenAPI plugin null pointer error persists even after: - Removing broken platform-repo submodule - Adding EXCLUDE flags for OSS repos - Enabling classic docs plugin in preset-classic Current error: Cannot read properties of null (reading '0') in docusaurus-plugin-openapi-docs/lib/index.js:67:39 Added troubleshooting plan for next session: - Debug locally to reproduce - Check classic docs plugin registration - Consider alternative approaches Status changed from FIXED to BLOCKED. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Root cause: The OpenAPI plugin had two issues: 1. Referenced docsPluginId "classic" but preset-classic uses "default" as its ID 2. Null plugin entries from EXCLUDE_* env vars caused null pointer errors Fixes: - Changed docsPluginId from "classic" to "default" (line 62) - Added .filter(Boolean) to plugins array to remove null entries (line 296) This resolves Issue #12 where docusaurus clean/gen-api-docs commands failed with "Cannot read properties of null (reading '0')" error. Tested locally: - npx docusaurus clean-api-docs platform ✅ - npx docusaurus gen-api-docs platform ✅ Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Documented the root cause and fix for Issue #12: - Changed docsPluginId from "classic" to "default" - Added .filter(Boolean) to remove null plugin entries - Both docusaurus commands now working with EXCLUDE env vars Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
The workflow was looking for the script at: openapi-overlay-generator/scripts/update_sidebar.py But it's actually located at: .claude/skills/openapi-overlay-generator/scripts/update_sidebar.py Updated the path in the "Update sidebar with new operations" step. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Root cause: When using workflow_dispatch with a PR number, checking out
refs/pull/{pr_number}/head results in detached HEAD state, causing
"fatal: You are not currently on a branch" error when trying to push.
Solution: Added a step to fetch the actual branch name from the PR first,
then checkout that branch directly. This ensures we're on an actual branch
when we commit and push changes.
Changes:
- Added "Get PR branch name" step using github-script
- Modified checkout to use the fetched branch name
- Works for both pull_request events and workflow_dispatch
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Added the fourth fix for Issue #12: - Fixed detached HEAD state when using workflow_dispatch - Workflow now fetches actual branch name from PR before checkout - Updated commits list with latest session commits Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Contributor
Author
✅ Overlays Applied and Docs RegeneratedAPI Version: 1.102.0 Changes Applied
Next Steps
This PR is now ready for final review and approval. |
Fixed 3 broken sidebar links from renamed doc IDs: - explore-data-link-1 → explore-data-link-with-path - generate-data-link-upload-url-1 → generate-data-link-upload-url-with-path - finish-data-link-upload-1 → finish-data-link-upload-with-path Added update_sidebar_v2.py with rename detection: - Validates existing sidebar entries against generated docs - Detects renamed files using fuzzy matching and pattern recognition - Supports auto-fix mode for high-confidence renames (≥80% similarity) - Recognizes common patterns like "-1" → "-with-path" suffix changes - Provides detailed suggestions with similarity scores This prevents future sidebar validation errors when doc IDs are renamed during OpenAPI spec regeneration. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
The change from 'classic' to 'default' was causing MDX compilation errors in local development. The real fix for the workflow was the .filter(Boolean) to remove null plugin entries from EXCLUDE env vars. Keeping docsPluginId as 'classic' for compatibility with local preview. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Root cause: The classic docs plugin was enabled in commit 88f6ed1 to fix the OpenAPI plugin error, but this caused the classic plugin to try processing OpenAPI-generated MDX files, which have a different format and caused "Unexpected FunctionDeclaration" compilation errors. The actual fix needed was just .filter(Boolean) to remove null plugin entries from EXCLUDE env vars. The OpenAPI plugin doesn't need the classic docs plugin to exist - it generates its own docs independently. Changes: - docs: { path: "platform-api-docs/docs", routeBasePath: "/" } → docs: false - Keeps .filter(Boolean) on plugins array (the real fix) - Keeps docsPluginId: "classic" (OpenAPI plugin config) Now local preview works correctly without MDX errors. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
The file was archived by the workflow after successful completion. Restoring it so the workflow can be triggered again to regenerate the correct MDX files with all the fixes applied. Restored from commit 038135d which contains all 14 overlays for v1.102.0. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Root cause: Commit 1caa91b already applied v1.102.0 overlays to the decorated spec. Running the workflow again would apply them twice, creating duplicate parameters and tags. Solution: Revert decorated spec to commit 8099d89 (v1.95 baseline) so overlays can be applied fresh without duplicates. This allows the workflow to run successfully and apply all fixes: - 14 overlays for v1.102.0 - No duplicate parameters - No duplicate tags - Clean validation Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Signed-off-by: Llewellyn vd Berg <113503285+llewellyn-sl@users.noreply.github.com>
Contributor
Author
✅ Overlays Applied and Docs RegeneratedAPI Version: 1.102.0 Changes Applied
Next Steps
This PR is now ready for final review and approval. |
Changes: - Deleted old update_sidebar.py (v1) - Deleted UPDATE_SIDEBAR_V2_README.md (standalone doc) - Updated main README.md with v2 features: - Validation mode for existing entries - Rename detection with fuzzy matching - Auto-fix mode for high-confidence renames - Pattern recognition (e.g., -1 → -with-path) - Updated workflow integration diagram - Added troubleshooting for rename detection The workflow now uses update_sidebar_v2.py which prevents future issues with renamed doc IDs during API regeneration. 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.
API Version: 1.102.0
This PR was automatically generated by the API docs workflow.
What's included
Next steps
claude-generated-overlays.mdpython scripts/validate_overlay.py <file>overlays-approvedto trigger Phase 3Analysis Summary
See analysis JSON file for detailed breakdown of changes.
Triggered by: joaquimgamero
Platform commit: 67834d1d4c69e9a509d8b999554604ca7df45bfb