Docs build improvements #683

acolytec3 · 2025-07-31T19:15:52Z

This continues work from #667 cleaning up the docs.

Rationalizes the dependencies since a few were no longer used and we had a division between dependencies and devDependencies that no longer makes sense since this isn't a package being published anywhere
Adds a new watch script for the docs that reloads the local dev server when changes are made to the spec or docs
Fixes a number of broken links in the docs

kclowes

Thanks for updating the links! Nice catch!

I am not seeing the watch command work. I haven't been able to track it down, but every now and then the first change I make will show up, but none after that. I make the change in the .md file, watch the output from the rebuild in the terminal, reload the page, and the change is still there. Any ideas?

acolytec3 · 2025-07-31T20:13:36Z

I fixed a bug in the nodemon --watch parameter. It should now rebuild every time you touch something in docs or src. You then need to reload the page to see your changes.

acolytec3 · 2025-07-31T20:17:24Z

Also, note, edits to the base README.md do not get added to the docs. I don't know a good way around this at present since when we copy the README to docs/reference/quickstart.md it puts the nodemon --watch script into an endless loop. The base issue here is that we copy the README in the first place. Since we're basically duplicating it to a second directory to deal with the somewhat complicated way we build the docs, we're always going to have this potential issue of people maybe trying to update the quickstart.md file that gets overwritten by the base repo README.

acolytec3 · 2025-07-31T20:20:43Z

At the end of the day, this is a somewhat sub-optimal solution. Ideally, gatsby would just rebuild every time we update the spec without needing to do a complete restart of the dev server. Since we're dependent on the openrpc generator for building the api spec and I haven't been able to figure out how to configure gatsby to rebuild those spec files using its hot module reload feature, we're stuck with restarting the server and then having the user refresh the page.

bomanaps · 2025-08-02T07:17:10Z

At the end of the day, this is a somewhat sub-optimal solution. Ideally, gatsby would just rebuild every time we update the spec without needing to do a complete restart of the dev server. Since we're dependent on the openrpc generator for building the api spec and I haven't been able to figure out how to configure gatsby to rebuild those spec files using its hot module reload feature, we're stuck with restarting the server and then having the user refresh the page.

Totally agree the current setup works, but it does feel a bit clunky, especially with the repeated restarts and the need to manually copy files around. One small improvement that might make things smoother for contributors (even if it doesn’t fully solve the hot reload issue) is to combine those separate steps into a single npm run dev script. That way, devs can just run one command and get everything going:
build the spec
generate the tests
copy the spec into Gatsby's docs path
start the dev server
Something like:

"scripts": {
  "dev": "npm run build && npm run build:test && cp ./openrpc.json build/docs/gatsby/src/openrpc.json && npm run watch"
}

I know it’s not a fix for the HMR issue, but at least it streamlines the workflow and hides some of the friction for contributors.
Happy to open a quick follow-up PR with this if that sounds helpful!

bomanaps

Is it possible to prevent nodemon from watching the destination file, more like telling nodemon to ignore the destination

"scripts": {
  "watch": "nodemon --watch src --watch docs --watch README.md --ignore docs/reference/quickstart.md --ext yaml,md,json --exec \"npm run build && cp ./openrpc.json build/docs/gatsby/src/openrpc.json && npm run serve\""
}

just for us to avoid the loop or another option would be to only copy README.md if it changed, we can use a small shell check

cmp -s README.md docs/reference/quickstart.md || cp README.md docs/reference/quickstart.md

the script might look like this

"scripts": {
  "dev": "npm run build && npm run build:test && cmp -s README.md docs/reference/quickstart.md || cp README.md docs/reference/quickstart.md && cp ./openrpc.json build/docs/gatsby/src/openrpc.json && npm run watch"
}

acolytec3 · 2025-08-02T17:27:52Z

Is it possible to prevent nodemon from watching the destination file, more like telling nodemon to ignore the destination
"scripts": {
  "watch": "nodemon --watch src --watch docs --watch README.md --ignore docs/reference/quickstart.md --ext yaml,md,json --exec \"npm run build && cp ./openrpc.json build/docs/gatsby/src/openrpc.json && npm run serve\""
}

Thanks for this suggestion. I wasn't aware of the ignore flag in nodemon. Have updated with that fix. This should be ready for merging pending CI passing.

zcstarr · 2025-08-05T02:39:47Z

package.json

@@ -6,14 +6,17 @@
  "scripts": {
    "build": "npm run build:spec",


nit. I think I would probably make build, build everything v just spe , and have the specific build for running specific stages as you have here. The rationale being if you're new to the repo, you'd git clone, npm run build . This would make it so you could then run test or launch docs right after, as you level up you'll probably run build:spec or whatever specific thing you're looking to run.

Good point. I've updated the build script to do everything..

zcstarr

Overall I think these changes look good

zcstarr

@acolytec3 you might need to also change the deploy.yaml to not run build with this change but run build:specs
https://github.com/ethereum/execution-apis/blob/main/.github/workflows/test-deploy.yaml#L32
and
https://github.com/ethereum/execution-apis/blob/main/.github/workflows/deploy.yaml#L28

Unfortunately you can't say just run build in ci unless you introduce the golang image into the CI for deploying the ghpages.

I think CI in general could maybe use a rethink or reworking, but that would be out of the scope of this PR. so my suggestion is to convert npm run build to npm run build:specs

kclowes

This LGTM once the comments about CI from @zcstarr are addressed!

acolytec3 · 2025-08-09T10:47:17Z

Thanks! Should be ready to merge.

acolytec3 · 2025-08-15T22:32:55Z

Can this get merged?

bomanaps · 2025-08-18T12:54:35Z

@lightclient @kclowes

lightclient

LGTM - thanks @acolytec3 🫡

acolytec3 added 5 commits July 31, 2025 14:25

Rationalize dependencies

49603a9

update package lock

1292d27

Add watch script

8b05db3

Update readme

730d259

Fix broken links and update quickstart

9783c78

kclowes reviewed Jul 31, 2025

View reviewed changes

Fix watch parameter

9b5bac3

bomanaps reviewed Aug 2, 2025

View reviewed changes

Include README in watched files

e7ec78f

zcstarr reviewed Aug 5, 2025

View reviewed changes

Make build script build everything

df6fc40

zcstarr reviewed Aug 8, 2025

View reviewed changes

kclowes reviewed Aug 8, 2025

View reviewed changes

acolytec3 added 2 commits August 9, 2025 06:35

Fix ci

4214c9c

spellcheck

7bebe9c

lightclient approved these changes Aug 20, 2025

View reviewed changes

lightclient merged commit e92738b into ethereum:main Aug 20, 2025
6 checks passed

Docs build improvements #683

Docs build improvements #683

Uh oh!

Conversation

acolytec3 commented Jul 31, 2025

Uh oh!

kclowes left a comment

Choose a reason for hiding this comment

Uh oh!

acolytec3 commented Jul 31, 2025

Uh oh!

acolytec3 commented Jul 31, 2025

Uh oh!

acolytec3 commented Jul 31, 2025

Uh oh!

bomanaps commented Aug 2, 2025

Uh oh!

bomanaps left a comment

Choose a reason for hiding this comment

Uh oh!

acolytec3 commented Aug 2, 2025

Uh oh!

zcstarr Aug 5, 2025

Choose a reason for hiding this comment

Uh oh!

acolytec3 Aug 7, 2025

Choose a reason for hiding this comment

Uh oh!

zcstarr left a comment

Choose a reason for hiding this comment

Uh oh!

zcstarr left a comment

Choose a reason for hiding this comment

Uh oh!

kclowes left a comment

Choose a reason for hiding this comment

Uh oh!

acolytec3 commented Aug 9, 2025

Uh oh!

acolytec3 commented Aug 15, 2025

Uh oh!

bomanaps commented Aug 18, 2025

Uh oh!

lightclient left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!