feat: add github action to generate typedoc json automatically #2555
Conversation
WalkthroughThis pull request introduces a new GitHub Actions workflow to automate the generation and deployment of TypeDoc documentation. Triggered on pushes to tags matching "v*" and manual initiation, the workflow performs steps such as checking out the repository, setting up Node.js with pnpm, building the engine, preparing the output directory, and executing a script to generate TypeDoc JSON documentation which is subsequently uploaded to a CDN. Additionally, the Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant GitHubActions
participant Checkout
participant NodeSetup
participant BuildEngine
participant TypedocScript
participant CDN
User->>GitHubActions: Push tag "v*" or trigger workflow_dispatch
GitHubActions->>Checkout: Checkout repository
GitHubActions->>NodeSetup: Setup pnpm and Node.js LTS
NodeSetup->>BuildEngine: Run engine build (pnpm b:all)
BuildEngine->>TypedocScript: Execute typedoc.sh (using TYPEDOC & OUTPUT_DIR)
TypedocScript->>CDN: Upload generated TypeDoc JSON
Possibly related PRs
Suggested labels
Suggested reviewers
Poem
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
.github/workflows/typedoc.yml (1)
40-43: Add error handling for version extraction.The version extraction from package.json should include error handling in case the file or version field is missing.
- name: Create package.json for galacean-typedoc run: | + if [ ! -f "${{ github.workspace }}/packages/galacean/package.json" ]; then + echo "Error: package.json not found" + exit 1 + fi VERSION=$(jq -r '.version' ${{ github.workspace }}/packages/galacean/package.json) + if [ -z "$VERSION" ] || [ "$VERSION" = "null" ]; then + echo "Error: version not found in package.json" + exit 1 + fi echo "{\"name\": \"galacean-typedoc\", \"version\": \"$VERSION\"}" > ${{ github.workspace }}/galacean-typedoc/package.json cat ${{ github.workspace }}/galacean-typedoc/package.json
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
.github/workflows/typedoc.yml(1 hunks)packages/core/src/physics/joint/Joint.ts(1 hunks)scripts/typedoc.sh(1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: build (22.x, windows-latest)
- GitHub Check: codecov
- GitHub Check: e2e (22.x)
🔇 Additional comments (5)
packages/core/src/physics/joint/Joint.ts (1)
288-288: Verify if commenting out joint rotation was intentional.This change disables the native joint rotation update, which seems unrelated to the PR's objective of adding TypeDoc generation. Please verify if this was intentional or if it was accidentally included.
Likely an incorrect or invalid review comment.
scripts/typedoc.sh (2)
9-10: LGTM! Good improvement in configurability.The addition of a configurable output directory with a sensible default is a good improvement that makes the script more flexible.
Also applies to: 17-19
7-7:❓ Verification inconclusive
Verify if TypeDoc version 0.23.28 is appropriate.
The script uses a fixed version of TypeDoc which is good for consistency, but version 0.23.28 is quite old.
🌐 Web query:
What is the latest version of TypeDoc and are there any known issues with version 0.23.28?💡 Result:
The latest version of TypeDoc is v0.27.7, released on February 9, 2025[1][9]. This update introduced several features and fixes:
- File injection via
@includeCode/@inlineusing regions or line numbers- Japanese localization improvements (replacing deprecated
jpwithja)- Enhanced
--watchmode for broader file monitoring[1][7]For version 0.23.x, no direct information about issues appears in the search results - this version predates current documentation references (which focus on ≥v0.27). However:
1. Known limitations from earlier versions that might apply:
- Older versions lacked modern validation features like link checking[7]
- Pre-v0.24 had different anchor generation rules[7]
- Earlier releases didn't support TypeScript ≥5.x features[1]
2. General upgrade considerations from release notes:
- Version 0.27 introduced breaking changes including ESM conversion and TS5+ requirements[1][7]
- Security scans show no vulnerabilities for current versions[6]
While no specific issues are documented for v0.23.28, users should upgrade due to significant improvements in:
- API documentation accuracy
- Markdown handling
- Watch mode reliability
- TypeScript compatibility (now requiring TS5+)[1][7][9]
Citations:
- 1: https://github.com/TypeStrong/typedoc/releases
- 2: https://socket.dev/npm/package/typedoc/versions
- 3: https://forum.babylonjs.com/t/versioned-documentation/25356
- 4: https://typedoc-plugin-markdown.org/docs/CHANGELOG
- 5: Typedoc should support complex @default values TypeStrong/typedoc#2219
- 6: https://security.snyk.io/package/npm/typedoc
- 7: https://typedoc.org/documents/Changelog.html
- 8: Uncaught ReferenceError: __dirname is not defined in browser using ReflectionKind TypeStrong/typedoc#2305
- 9: https://www.npmjs.com/package/typedoc?activeTab=versions
- 10: https://issues.ecosyste.ms/hosts/GitHub/repositories/orkestral%2Fvenom/issues?page=4&per_page=100
Action: Verify TypeDoc Version and Consider Future Upgrade
- The fixed version (typedoc@0.23.28) ensures consistency but is significantly older than the current release (v0.27.7 as of February 2025).
- Although no explicit issues or vulnerabilities were reported for v0.23.28, this version lacks several improvements found in later releases (e.g., enhanced watch mode, improved Markdown handling, and better TypeScript ≥5.x compatibility).
- The configurable output directory setup is a strong improvement and can remain as is.
Please verify whether the benefits of upgrading to v0.27.7 outweigh any potential compatibility or stability concerns in your project.
.github/workflows/typedoc.yml (2)
5-64: LGTM! Well-structured workflow with good security practices.The workflow is well-structured with appropriate triggers, minimal permissions, and secure handling of sensitive data.
32-32:✅ Verification successful
Verify Node.js version requirement.
The workflow requires Node.js
>=22.6.0which is unusually high and not an LTS version. Consider using an LTS version for better stability.
🌐 Web query:
What is the current LTS version of Node.js?💡 Result:
The current Long Term Support (LTS) version of Node.js is v22.x (codename "Jod"), which entered Active LTS status on October 29, 2024[1][7]. This version will receive critical updates and security patches until April 30, 2027[1][8], with:
- Active LTS support through October 21, 2025
- Maintenance LTS support continuing until April 30, 2027[7][8]
Key features of this LTS release include:
- Built-in WebSocket client for real-time communication[1]
- Enhanced stability for production environments[1]
- Extended support timeline compared to previous versions like Node.js 20 (now in maintenance mode)[1][5]
Major platforms like Netlify have adopted Node.js v22 as their default runtime since January 2025[3], and it remains the recommended choice for production systems requiring long-term reliability[8]. The next LTS release (v24.x) is scheduled for April 2025[7].
Citations:
- 1: http://nodesource.com/blog/Node.js-v22-Long-Term-Support-LTS/
- 2: https://www.nearform.com/digital-community/node-js-release-schedule-explained
- 3: https://answers.netlify.com/t/builds-functions-plugins-default-node-js-version-upgrade-to-22/135981
- 4: https://nodejs.org/en
- 5: https://nodejs.org/en/about/previous-releases
- 6: https://endoflife.date/nodejs
- 7: https://github.com/nodejs/Release
- 8: https://www.herodevs.com/blog-posts/node-js-end-of-life-dates-you-should-be-aware-of
- 9: https://community.auth0.com/t/node-js-22-or-20-for-running-actions/153963
- 10: https://www.herodevs.com/blog-posts/node-js-18-end-of-life-what-it-means-and-how-to-prepare
Node.js Version Requirement Validated
The Node.js version configured as
>=22.6.0is correct—it aligns with the current LTS Node.js v22.x release ("Jod"), providing the expected stability and long-term support. No changes regarding the Node.js version are required at this time. You might still review the version extraction logic and consider adding path filters if beneficial.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
.github/workflows/typedoc.yml (3)
5-9: Consider adding branch restrictions for manual workflow dispatch.The workflow can be manually triggered on any branch. Consider restricting manual runs to specific branches (e.g., main/master) to maintain better control over documentation generation.
on: push: tags: - "v*" workflow_dispatch: + branches: + - main # or your default branch
43-46: Add error handling for version extraction.The version extraction process could fail silently. Consider adding error handling and validation.
run: | + if [ ! -f "${{ github.workspace }}/packages/galacean/package.json" ]; then + echo "Error: package.json not found" + exit 1 + fi VERSION=$(jq -r '.version' ${{ github.workspace }}/packages/galacean/package.json) + if [ -z "$VERSION" ]; then + echo "Error: Failed to extract version" + exit 1 + fi echo "{\"name\": \"galacean-typedoc\", \"version\": \"$VERSION\"}" > ${{ github.workspace }}/galacean-typedoc/package.json cat ${{ github.workspace }}/galacean-typedoc/package.json
1-10: Add timeout and concurrency settings for better workflow management.Consider adding timeout and concurrency settings to prevent long-running or conflicting workflow executions.
name: Generate TypeDoc on: push: tags: - "v*" workflow_dispatch: + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true jobs: release: + timeout-minutes: 30
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
.github/workflows/typedoc.yml(1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: build (22.x, windows-latest)
- GitHub Check: e2e (22.x)
- GitHub Check: codecov
🔇 Additional comments (2)
.github/workflows/typedoc.yml (2)
11-17: Well-configured job permissions!The job uses appropriate permissions following the principle of least privilege, requesting only the necessary write access for contents and id-token.
54-57: Reconsider running upload step on workflow failure.The upload step runs even when the workflow fails (
if: success() || failure()). This could potentially upload invalid or incomplete documentation. Consider running only on success unless there's a specific reason to keep failed artifacts.- if: success() || failure() + if: success()
| node-version: '>=22.6.0' | ||
| registry-url: https://registry.npmjs.org/ | ||
| cache: pnpm |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Specify an exact Node.js version for reproducible builds.
Using >=22.6.0 could lead to inconsistent builds across different environments. Consider pinning to a specific LTS version.
- node-version: '>=22.6.0'
+ node-version: '22.6.0'📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| node-version: '>=22.6.0' | |
| registry-url: https://registry.npmjs.org/ | |
| cache: pnpm | |
| node-version: '22.6.0' | |
| registry-url: https://registry.npmjs.org/ | |
| cache: pnpm |
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #2555 +/- ##
==========================================
+ Coverage 68.91% 68.92% +0.01%
==========================================
Files 961 961
Lines 100266 100266
Branches 8679 8686 +7
==========================================
+ Hits 69094 69107 +13
+ Misses 30912 30899 -13
Partials 260 260
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. |
Summary by CodeRabbit