Skip to content

Commit d45bea5

Browse files
LesnyRumcajsLesnyRumcajs
committed
feat(docs): RPC methods reference
1 parent a9f8cf1 commit d45bea5

File tree

14 files changed

+7959
-10448
lines changed

14 files changed

+7959
-10448
lines changed

‎.github/workflows/docs-rpc-auto-update.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# This workflow, run daily, updates the Forest RPC reference docs, and submits a PR with the changes.
2+
name: Update Forest RPC reference docs
3+
4+
on:
5+
workflow_dispatch:
6+
schedule:
7+
- cron: "0 0 * * *"
8+
9+
jobs:
10+
update-docs:
11+
runs-on: ubuntu-slim
12+
steps:
13+
- uses: actions/checkout@v6
14+
- name: Generate OpenRPC specifications
15+
run: |
16+
cd docs/scripts
17+
./generate-openrpc-specs.sh docker
18+
- uses: actions/setup-node@v6
19+
with:
20+
node-version: 20
21+
package-manager-cache: false
22+
- run: corepack enable
23+
- name: Generate RPC reference from OpenRPC specs
24+
run: |
25+
cd docs
26+
pnpm i --frozen-lockfile
27+
pnpm generate:rpc-reference
28+
# This is needed in order to have the commits signed.
29+
- uses: actions/create-github-app-token@v2
30+
id: generate-token
31+
with:
32+
app-id: ${{ secrets.LESHY_APP_ID }}
33+
private-key: ${{ secrets.LESHY_APP_PRIVATE_KEY }}
34+
- name: Create Pull Request
35+
uses: peter-evans/create-pull-request@v8
36+
with:
37+
base: main
38+
branch: leshy/update-forest-rpc-docs
39+
token: ${{ steps.generate-token.outputs.token }}
40+
commit-message: Update Forest RPC reference docs
41+
sign-commits: true
42+
title: "[automated] Update Forest RPC reference docs"
43+
body: |
44+
### Changes
45+
- Updates Forest RPC reference docs to the latest commit in the `main` branch.
46+
- Regenerates OpenRPC specifications (v0, v1, v2) from latest Forest code.
47+
- Regenerates RPC method reference data from OpenRPC specs.

‎docs/.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,12 @@
88
# Docusaurus Build Directory
99
/build/
1010

11+
# Generated RPC reference data
12+
/src/data/rpc-methods.json
13+
14+
# Generated OpenRPC specifications (auto-generated from Forest)
15+
/openrpc-specs/
16+
1117
### Docusaurus.Node Stack ###
1218
# Logs
1319
logs

‎docs/.prettierignore‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# OpenRPC specification files (auto-generated from Forest)
2+
openrpc-specs/
3+
4+
# Lock files
5+
pnpm-lock.yaml
6+
package-lock.json
7+
yarn.lock
8+
9+
# Build output
10+
build/
11+
.docusaurus/
12+
13+
# Generated data
14+
src/data/rpc-methods.json

‎docs/ANCHOR_LINKS_GUIDE.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# RPC Reference - Direct Links Guide
2+
3+
## How to Get a Direct Link to a Method
4+
5+
The RPC reference page supports direct links to specific methods. Here's how to use them:
6+
7+
### Getting a Link
8+
9+
1. **Navigate to the method** on the [JSON-RPC Methods Reference](/docs/users/reference/json_rpc_methods) page
10+
2. **Click the 🔗 icon** next to the method name
11+
3. **The link is copied to your clipboard** (the icon changes to ✓ briefly)
12+
4. **Paste and share** the link with others
13+
14+
### How Links Work
15+
16+
When someone clicks your link:
17+
18+
- ✅ The correct API version is **automatically selected**
19+
- ✅ The method card is **automatically expanded**
20+
- ✅ The page **scrolls to the method**
21+
22+
### Link Format
23+
24+
Links use URL hash anchors with this format:
25+
26+
```
27+
#method-{version}-{methodName}
28+
#namespace-{version}-{namespace}
29+
```
30+
31+
### Examples
32+
33+
**Method links:**
34+
35+
- `/docs/users/reference/json_rpc_methods#method-v0-Filecoin.ChainHead`
36+
- Opens v0 API
37+
- Expands and scrolls to `Filecoin.ChainHead`
38+
39+
- `/docs/users/reference/json_rpc_methods#method-v1-eth_blockNumber`
40+
- Opens v1 API
41+
- Expands and scrolls to `eth_blockNumber`
42+
43+
- `/docs/users/reference/json_rpc_methods#method-v2-Filecoin.StateGetActor`
44+
- Opens v2 API
45+
- Expands and scrolls to `Filecoin.StateGetActor`
46+
47+
**Namespace links:**
48+
49+
- `/docs/users/reference/json_rpc_methods#namespace-v0-Filecoin`
50+
- Opens v0 API
51+
- Filters by Filecoin namespace
52+
- Scrolls to the namespace section
53+
54+
- `/docs/users/reference/json_rpc_methods#namespace-v1-eth`
55+
- Opens v1 API
56+
- Filters by eth namespace
57+
- Scrolls to the namespace section
58+
59+
## Testing
60+
61+
To test if links work correctly:
62+
63+
1. **Copy a link** using the 🔗 button
64+
2. **Open in a new tab** or share with someone
65+
3. **Verify** that:
66+
- The correct version is selected in the dropdown
67+
- The method is expanded
68+
- The page scrolled to the right location
69+
70+
## Implementation Details
71+
72+
The anchor link system:
73+
74+
- Uses React's `useEffect` hook to listen for URL hash changes
75+
- Parses the hash to extract version and method/namespace
76+
- Automatically switches versions if needed
77+
- Expands methods and scrolls with smooth scrolling
78+
- Works with browser back/forward buttons
79+
- Supports direct navigation from external links
80+
81+
## Troubleshooting
82+
83+
**Link doesn't scroll to method:**
84+
85+
- The page might still be loading - wait a moment and scroll manually
86+
- Try refreshing the page
87+
88+
**Wrong version shown:**
89+
90+
- The version is encoded in the link - check that the link format is correct
91+
- Example: `#method-v1-Filecoin.ChainHead` (v1) vs `#method-v0-Filecoin.ChainHead` (v0)
92+
93+
**Method not expanding:**
94+
95+
- The method name in the link must exactly match the method name in the API
96+
- Method names are case-sensitive (e.g., `Filecoin.ChainHead` not `filecoin.chainhead`)

‎docs/README.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,17 @@ These docs are automatically generated from the Forest CLI. See [script](/docs/d
6262

6363
#### JSON-RPC Docs
6464

65-
We use the OpenRPC document from Forest to populate the documentation for each method. For this we use `@metamask/docusaurus-openrpc`.
65+
We maintain comprehensive RPC documentation generated from the OpenRPC specification:
66+
67+
1. **Method Reference** - An interactive, searchable reference for all 246 RPC methods. Generated automatically from `docs/users/openrpc.json` by a build script. See [RPC_REFERENCE.md](./RPC_REFERENCE.md) for details.
68+
69+
2. **OpenRPC Schema Explorer** - An external playground linked from the docs for exploring the full schema interactively.
70+
71+
To regenerate the method reference after updating `openrpc.json`:
72+
73+
```bash
74+
pnpm generate:rpc-reference
75+
```
6676

6777
### Developer Docs
6878

‎docs/RPC_AUTO_UPDATE_SUMMARY.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# Summary: RPC Reference Auto-Generation System
2+
3+
## What Changed
4+
5+
### ✅ Removed Static OpenRPC Files
6+
7+
- **Deleted**: `docs/openrpc/` directory with v0.json, v1.json, v2.json
8+
- These were static files that needed manual updates
9+
10+
### ✅ Added Dynamic OpenRPC Generation
11+
12+
- **Created**: `docs/scripts/generate-openrpc-specs.sh`
13+
- Extracts OpenRPC specs directly from Forest using `forest-tool shed openrpc`
14+
- Supports both Docker (`./generate-openrpc-specs.sh docker`) and local builds (`./generate-openrpc-specs.sh local`)
15+
- Generates files in `docs/openrpc-specs/` (gitignored)
16+
17+
### ✅ Updated TypeScript Generator
18+
19+
- **Modified**: `docs/scripts/generate-rpc-reference.ts`
20+
- Changed source path from `openrpc/` to `openrpc-specs/`
21+
- No other changes needed
22+
23+
### ✅ Added Automated Workflow
24+
25+
- **Created**: `.github/workflows/docs-rpc-auto-update.yml`
26+
- Runs daily at midnight UTC
27+
- Can be triggered manually via workflow_dispatch
28+
- Steps:
29+
1. Generates fresh OpenRPC specs from Forest (via Docker)
30+
2. Regenerates RPC reference data from specs
31+
3. Creates a PR with changes (if any)
32+
- Based on existing `docs-auto-update.yml` workflow
33+
34+
### ✅ Updated Configuration Files
35+
36+
- **Modified**: `docs/.gitignore`
37+
- Added `openrpc-specs/` to ignore generated OpenRPC files
38+
- **Modified**: `docs/.prettierignore`
39+
- Changed `openrpc/` to `openrpc-specs/`
40+
- **Modified**: `docs/RPC_REFERENCE.md`
41+
- Updated documentation to explain new workflow
42+
- Added instructions for OpenRPC generation
43+
44+
## How It Works Now
45+
46+
### Manual Process (Local Development)
47+
48+
1. **Generate OpenRPC specs from Forest**:
49+
50+
```bash
51+
cd docs/scripts
52+
./generate-openrpc-specs.sh docker # or 'local' if Forest is built
53+
```
54+
55+
2. **Generate RPC reference data**:
56+
57+
```bash
58+
cd docs
59+
pnpm generate:rpc-reference
60+
```
61+
62+
3. **Build/serve docs**:
63+
```bash
64+
pnpm start # or pnpm build
65+
```
66+
67+
### Automated Process (GitHub Actions)
68+
69+
Every day at midnight UTC:
70+
71+
1. Workflow runs on `ubuntu-slim` runner
72+
2. Checks out the repository
73+
3. Runs `generate-openrpc-specs.sh docker` to get latest specs
74+
4. Runs `pnpm generate:rpc-reference` to process them
75+
5. Creates a PR if any changes detected
76+
77+
The workflow uses the Leshy bot (GitHub App) for signed commits.
78+
79+
## Benefits
80+
81+
### Before (Static Approach)
82+
83+
- ❌ OpenRPC files manually updated
84+
- ❌ Could get out of sync with Forest code
85+
- ❌ Required manual PR when RPC methods changed
86+
- ✅ Simpler (no Docker dependency)
87+
88+
### After (Dynamic Approach)
89+
90+
- ✅ OpenRPC specs auto-generated from Forest
91+
- ✅ Always in sync with latest Forest code
92+
- ✅ Automated daily updates via workflow
93+
- ✅ Can be run locally with Docker (no Forest build needed)
94+
- ✅ Follows same pattern as CLI docs workflow
95+
96+
## Files Summary
97+
98+
### Created
99+
100+
- `.github/workflows/docs-rpc-auto-update.yml` - Daily auto-update workflow
101+
- `docs/scripts/generate-openrpc-specs.sh` - OpenRPC extraction script
102+
- `docs/openrpc-specs/` - Directory for generated specs (gitignored)
103+
104+
### Modified
105+
106+
- `docs/scripts/generate-rpc-reference.ts` - Updated path from `openrpc/` to `openrpc-specs/`
107+
- `docs/.gitignore` - Added `openrpc-specs/` to ignore list
108+
- `docs/.prettierignore` - Updated to ignore `openrpc-specs/` instead of `openrpc/`
109+
- `docs/RPC_REFERENCE.md` - Updated documentation with new workflow
110+
111+
### Deleted
112+
113+
- `docs/openrpc/` - Old static OpenRPC directory removed
114+
115+
## Testing
116+
117+
All checks pass:
118+
119+
- ✅ TypeScript compilation
120+
- ✅ Prettier formatting
121+
- ✅ Spellcheck
122+
- ✅ Build (pnpm build)
123+
- ✅ OpenRPC generation from Docker
124+
- ✅ RPC reference generation from specs
125+
126+
## Next Steps for User
127+
128+
1. **Test the workflow manually**:
129+
- Go to GitHub Actions → "Update Forest RPC reference docs"
130+
- Click "Run workflow" to trigger manually
131+
- Verify it creates a PR successfully
132+
133+
2. **Monitor daily runs**:
134+
- The workflow will run daily at midnight UTC
135+
- Check that PRs are created when RPC methods change
136+
137+
3. **Local development** (if needed):
138+
```bash
139+
cd docs/scripts
140+
./generate-openrpc-specs.sh docker
141+
cd ..
142+
pnpm generate:rpc-reference
143+
pnpm start
144+
```
145+
146+
## Commands Reference
147+
148+
### For CI/CD (GitHub Actions)
149+
150+
```bash
151+
cd docs/scripts
152+
./generate-openrpc-specs.sh docker
153+
cd ..
154+
pnpm i --frozen-lockfile
155+
pnpm generate:rpc-reference
156+
```
157+
158+
### For Local Development (with Docker)
159+
160+
```bash
161+
cd docs/scripts
162+
./generate-openrpc-specs.sh docker
163+
cd ..
164+
pnpm generate:rpc-reference
165+
pnpm start
166+
```
167+
168+
### For Local Development (with local Forest)
169+
170+
```bash
171+
cd docs/scripts
172+
./generate-openrpc-specs.sh local
173+
cd ..
174+
pnpm generate:rpc-reference
175+
pnpm start
176+
```

0 commit comments

Comments
 (0)