Switch docs back to `openrpc` v2 #667

acolytec3 · 2025-06-18T15:11:49Z

This replaces the #653 docs project with the OpenRPC v2 docs generator so reverts back to the Gatsby build for now, based on #660.

Major changes

Replace docusaurus docs builder with OpenRPC v2 generator (i.e. gatsby)
Remove extraneous docusaurus artifacts
Adds gatsby-config that is copied to gatsby build and adds menu items for our docs
Moves tests/README.md to docs/reference/tests.md so it is accessible from docs
Copies repo README.md to docs/reference/quickstart.md so accessible from docs

Miscellaneous

Fixes spelling CI failures left over from add eth_simulateV1 #484

Docusaurus

Co-authored-by: lightclient <[email protected]>

update openrpc to v2

edit after build add contents write add path-prefix use peaceiris rework install setup rebuild gatsby again update config and deployment Add actions bot back to peace iris

acolytec3 · 2025-06-18T15:18:36Z

It now renders like this:

acolytec3 · 2025-06-18T15:18:51Z

We should be sure to squash all this to one commit if/when merged.

bomanaps · 2025-06-20T12:44:30Z

So the speccheck -v is failing not your fault but from the rpctestgen it has to do with this invalid result /eth_simulateV1/ethSimulate-add-more-non-defined-BlockStateCalls-than-fit-but-now-with-fit [I#] [S#] doesn't validate with file:///workspace/execution-apis/eth_simulateV1.result# [I#] [S#/type] expected object, but got array I will open an issue and try fixing that so the CI can run properly.

zcstarr

I think overall looks good jsut a few things around the package use and CI that will clean things up. I also had a qustion about using mjs in this repo for the most part. Generator uses the .js here but I think maybe there's an opp to switch back to mjs as it'll be more future proof. I'll test this when I bump the generator version

.github/workflows/deploy.yaml

zcstarr · 2025-06-25T00:21:40Z

.github/workflows/deploy.yaml

would be cool if we could stay on actions I think for long term usability

I'm not sure what you mean here. Can you clarify?

docs/config/gatsby-config.js

zcstarr · 2025-06-25T00:23:32Z

package.json

-    "lint": "npm run build:spec && node scripts/validate.mjs && node scripts/graphql-validate.mjs",
+    "build:spec": "node scripts/build.js",
+    "build:docs": "npm run generate-clients && npm run build:docs:gatsby",
+    "build:docs:gatsby": "cp docs/config/gatsby-config.js build/docs/gatsby && cd build/docs/gatsby && npm install && gatsby build --prefix-paths",


I think this will be cleaned up via the generator changes that will allow you to spec paths in the config.json

zcstarr · 2025-06-25T00:28:04Z

docs/config/gatsby-config.js

+    siteUrl: process.env.GITHUB_REPOSITORY 
+      ? `https://${process.env.GITHUB_REPOSITORY.split('/')[0]}.github.io/execution-apis`
+      : 'https://ethereum.github.io/execution-apis', // fallback for local development
+    logoUrl: 'https://raw.githubusercontent.com/open-rpc/design/master/icons/open-rpc-logo-noText/open-rpc-logo-noText%20(PNG)/256x256.png',


If there's an eth icon or one for execution apis we might drop that here.

zcstarr · 2025-06-25T00:30:37Z

docs/reference/ethsimulatev1-notes.md

I think @bomanaps mentioned it earlier there seems to be a formatting issue with the markdown table here. We might consider switching to .mdx to give these a little more spacing or container

Could be but that's really beyond the scope of this PR (which is intended to be isolated to migrating back to OpenRPC generator). Ideally that sort of stuff would be addressed separately.

please take a look at this @zcstarr acolytec3#5

This change allows for documentation assets to be copied by the generator into the proper build locations, eliminating the need for manual copy.

update support for latest generator

acolytec3 · 2025-07-07T15:20:56Z

Just noticed there were still merge conflicts. Will clean them up.

lightclient · 2025-07-07T16:06:13Z

Trying to run this locally, but it fails to generate with node version 22.17.0.

npm run build:docs:gatsby

> [email protected] build:docs:gatsby
> cd build/docs/gatsby && npm install && gatsby build --prefix-paths

npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error
npm error While resolving: [email protected]
npm error Found: [email protected]
npm error node_modules/react
npm error   react@"^18.0.0" from the root project
npm error
npm error Could not resolve dependency:
npm error peer react@"^16.0.0-0" from [email protected]
npm error node_modules/react-split-pane
npm error   react-split-pane@"^0.1.87" from the root project
npm error
npm error Fix the upstream dependency conflict, or retry
npm error this command with --force or --legacy-peer-deps
npm error to accept an incorrect (and potentially broken) dependency resolution.
npm error
npm error
npm error For a full report see:
npm error /Users/matt/.npm/_logs/2025-07-07T16_04_53_481Z-eresolve-report.txt
npm error A complete log of this run can be found in: /Users/matt/.npm/_logs/2025-07-07T16_04_53_481Z-debug-0.log

acolytec3 · 2025-07-07T18:08:59Z

Trying to run this locally, but it fails to generate with node version 22.17.0.

npm run build:docs:gatsby

> [email protected] build:docs:gatsby
> cd build/docs/gatsby && npm install && gatsby build --prefix-paths

npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error
npm error While resolving: [email protected]
npm error Found: [email protected]
npm error node_modules/react
npm error   react@"^18.0.0" from the root project
npm error
npm error Could not resolve dependency:
npm error peer react@"^16.0.0-0" from [email protected]
npm error node_modules/react-split-pane
npm error   react-split-pane@"^0.1.87" from the root project
npm error
npm error Fix the upstream dependency conflict, or retry
npm error this command with --force or --legacy-peer-deps
npm error to accept an incorrect (and potentially broken) dependency resolution.
npm error
npm error
npm error For a full report see:
npm error /Users/matt/.npm/_logs/2025-07-07T16_04_53_481Z-eresolve-report.txt
npm error A complete log of this run can be found in: /Users/matt/.npm/_logs/2025-07-07T16_04_53_481Z-debug-0.log

Can you document what steps you use to hit this issue?

I deleted build and node-modules and then do

npm i
npm run build
npm run build:docs

And everything compiles and build on node 22.17.0.

acolytec3 and others added 30 commits May 13, 2025 22:33

add docusaurus

909208b

update deploy scripts

19ac475

clean up stuff

5b0c81b

update action

6e0dc69

workflow dispatch trigger

f272141

build against main

406f4eb

Merge remote-tracking branch 'upstream/main' into docusaurus

9eef24a

Merge pull request #1 from acolytec3/docusaurus

54c3163

Docusaurus

push build to correct place

6bb9628

use correct working directory

b3a20fc

fix references

1612d44

update build artifact path in deploy workflow

e15e33e

consolidate in base dir

4557be6

more cleanup

caf5990

add test deploy ci

8b0a015

add workflow_dispatch

1d5d76a

fix deploy script

0f036d9

build specs and website

55d1bda

don't throw on broken links

fb9286f

update baseUrl

e4a3ddd

make ESM/CJS stuff play nice

929cd81

clean up links and docusaurus references

4719822

more link cleanup

0608537

update links to point to ethereum

87e206e

remove docu boilerplate

b63f4c4

build docs too

13b1f6e

Update docs/reference/intro.md

5e218ea

Co-authored-by: lightclient <[email protected]>

Update docusaurus.config.ts

b5fff3b

Co-authored-by: lightclient <[email protected]>

remove old deployment job

4331158

remove gatsby

2325067

acolytec3 added 9 commits June 13, 2025 15:43

Merge pull request #2 from acolytec3/openrpc-v2

b0ef8a4

update openrpc to v2

switch to module

7b920a7

put prefix back to empty string

8820122

specify prefix

c5f4697

use crazy-max

31e8683

edit after build add contents write add path-prefix use peaceiris rework install setup rebuild gatsby again update config and deployment Add actions bot back to peace iris

Merge remote-tracking branch 'upstream/main'

453178b

update spellcheck

035eb3d

make repo name dynamic

c95d608

dynamically add all md to menu

0788d9f

Remove copy docs step and reorder menu links

6f17bb6

zcstarr reviewed Jun 25, 2025

View reviewed changes

zcstarr and others added 5 commits June 27, 2025 21:27

update support for latest generator

989bb02

This change allows for documentation assets to be copied by the generator into the proper build locations, eliminating the need for manual copy.

Merge pull request #4 from zcstarr/feat/generator_update

3c4dc1a

update support for latest generator

remove node options detritus from deploy

fbfcec3

chore: change to mdx

94ce9fd

Replace styled table with remarkGfm plugin

3dabe2a

jflo mentioned this pull request Jul 6, 2025

# RPC Standards # 8 | July 7th, 2025 ethereum/pm#1605

Closed

Merge remote-tracking branch 'upstream/main'

5f630dd

Clean up links and add tests/quickstart to docs

48f8b82

acolytec3 mentioned this pull request Jul 9, 2025

Metamask OpenRPC Docusaurus Plugin - Deprecated #660

Open

update test deploy to check on node 20, 22, 24

11a9b3d

bomanaps mentioned this pull request Jul 18, 2025

RPC Standards # 9 | July 21, 2025 ethereum/pm#1630

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Switch docs back to `openrpc` v2 #667

Switch docs back to `openrpc` v2 #667

Uh oh!

acolytec3 commented Jun 18, 2025 •

edited

Loading

Uh oh!

acolytec3 commented Jun 18, 2025

Uh oh!

acolytec3 commented Jun 18, 2025

Uh oh!

bomanaps commented Jun 20, 2025

Uh oh!

zcstarr left a comment

Uh oh!

Uh oh!

zcstarr Jun 25, 2025

Uh oh!

acolytec3 Jun 26, 2025

Uh oh!

Uh oh!

zcstarr Jun 25, 2025 •

edited

Loading

Uh oh!

zcstarr Jun 25, 2025

Uh oh!

zcstarr Jun 25, 2025

Uh oh!

acolytec3 Jun 26, 2025

Uh oh!

bomanaps Jul 2, 2025

Uh oh!

acolytec3 commented Jul 7, 2025

Uh oh!

lightclient commented Jul 7, 2025

Uh oh!

acolytec3 commented Jul 7, 2025

Uh oh!

Uh oh!

Switch docs back to openrpc v2 #667

Are you sure you want to change the base?

Switch docs back to openrpc v2 #667

Uh oh!

Conversation

acolytec3 commented Jun 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

acolytec3 commented Jun 18, 2025

Uh oh!

acolytec3 commented Jun 18, 2025

Uh oh!

bomanaps commented Jun 20, 2025

Uh oh!

zcstarr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

zcstarr Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

acolytec3 Jun 26, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

zcstarr Jun 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zcstarr Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

zcstarr Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

acolytec3 Jun 26, 2025

Choose a reason for hiding this comment

Uh oh!

bomanaps Jul 2, 2025

Choose a reason for hiding this comment

Uh oh!

acolytec3 commented Jul 7, 2025

Uh oh!

lightclient commented Jul 7, 2025

Uh oh!

acolytec3 commented Jul 7, 2025

Uh oh!

Uh oh!

Switch docs back to `openrpc` v2 #667

Switch docs back to `openrpc` v2 #667

acolytec3 commented Jun 18, 2025 •

edited

Loading

zcstarr Jun 25, 2025 •

edited

Loading