feat: genlayercli api reference auto generated#247
Conversation
WalkthroughAdds a GitHub Actions workflow to generate and sync CLI MDX docs to the genlayer-docs repo on release or manual dispatch, adds an npm script to run a new Node script, implements a Node-based CLI help parser that emits MDX pages into docs/api-references, and updates the publish workflow to ignore docs/** pushes. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Maintainer
participant GH as GitHub Actions (CLI Repo)
participant CLI as CLI Project
participant Docs as genlayer-docs Repo
participant PR as PR Creator
Maintainer->>GH: workflow_dispatch or release published
GH->>CLI: checkout, setup Node, npm install, build
GH->>CLI: run npm run docs:cli
GH->>CLI: generate MDX under docs/api-references
alt non-beta release or manual dispatch
GH->>CLI: commit & push API refs to CLI repo (if changed)
end
GH->>Docs: checkout docs repo into branch docs/cli/...
GH->>Docs: rsync generated MDX to pages/api-references/genlayer-cli/
GH->>Docs: commit & push branch if changes
GH->>PR: create PR (if changes)
sequenceDiagram
autonumber
participant Gen as generate-cli-docs.mjs
participant CLI as dist/index.js --help
participant FS as Filesystem
Gen->>FS: read package.json (name, version, description)
Gen->>CLI: run --help for root command
Gen->>Gen: parse description, usage, options, subcommands, args
loop BFS over commands
Gen->>CLI: run --help for subcommand
Gen->>Gen: parse and collect command info
Gen->>FS: write MDX page for command (docs/api-references/...)
end
Gen->>FS: write index MDX and _meta.json
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
✨ Finishing Touches
🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type 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: 3
🧹 Nitpick comments (2)
scripts/generate-cli-docs.mjs (1)
175-179: Log errors instead of silently swallowing themThe empty catch block silently ignores all errors, which could hide important issues during cleanup.
async function rmrf(dir) { try { await fs.rm(dir, { recursive: true, force: true }); - } catch {} + } catch (err) { + console.warn(`Warning: Failed to remove directory ${dir}:`, err.message); + } }.github/workflows/cli-docs.yml (1)
121-121: Remove extra blank line at end of file- labels: documentation, cli - - + labels: documentation, cli
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
.github/workflows/cli-docs.yml(1 hunks).github/workflows/publish.yml(1 hunks)package.json(1 hunks)scripts/generate-cli-docs.mjs(1 hunks)
🧰 Additional context used
🪛 actionlint (1.7.7)
.github/workflows/cli-docs.yml
110-110: could not parse as YAML: yaml: line 110: mapping values are not allowed in this context
(syntax-check)
🪛 YAMLlint (1.37.1)
.github/workflows/cli-docs.yml
[warning] 121-121: too many blank lines (2 > 0)
(empty-lines)
[error] 110-110: syntax error: mapping values are not allowed here
(syntax)
🔇 Additional comments (3)
.github/workflows/publish.yml (1)
8-9: LGTM!Appropriately excludes documentation-only changes from triggering the release workflow, preventing unnecessary release cycles.
package.json (1)
18-19: LGTM!The new
docs:cliscript is properly defined and the formatting is consistent with the file structure..github/workflows/cli-docs.yml (1)
90-102: Fix undefined VERSION variable referenceLine 96 references
${VERSION:-${{ env.VERSION }}}but VERSION is not defined in this shell context. Use the step output directly.- git commit -m "docs(cli): sync API reference ${VERSION:-${{ env.VERSION }}}" + git commit -m "docs(cli): sync API reference ${{ steps.version.outputs.value }}"Likely an incorrect or invalid review comment.
2 participants
Add Automated CLI Docs Generation and Sync
Summary
Implements automatic GenlayerCLI command reference generation and synchronization:
docs/api-references.pages/api-references/genlayer-cli.This eliminates manual drift between CLI changes and documentation.
Changes
🚀 New Features
docs/api-referenceslocally and in CI.🔧 Implementation Details
node dist/index.js --help(and each subcommand’s help) to extract command metadata. Avoids importing source or changing the CLI entry.DOCS_CLEAN=trueto remove stale pages when commands are removed/renamed.📁 File Structure
🏗️ Architecture
dist/index.js.docs/api-referenceson non-beta releases.pages/api-references/genlayer-cliand open a PR.🧪 Testing
npm run build && npm run docs:cliproduces MDX files underdocs/api-references.🔧 Usage
✨ Code Quality
src/index.ts) or command registrations.docs(cli): update API reference for <version>docs(cli): sync API reference <version>🔗 Dependencies
dist/index.js).🛡️ Backward Compatibility
publishworkflow ignoresdocs/**changes to prevent re-trigger loops.📚 Documentation Updates
docs/api-references/.pages/api-references/genlayer-cli.Testing: ✅ Verified locally and via workflow design
Safety: ✅ No changes to runtime CLI behavior
DX: ✅ Eliminates manual docs updates, keeps docs current on releases
Summary by CodeRabbit
New Features
Documentation
Chores