Docs build improvements (#683)

* Rationalize dependencies

* update package lock

* Add watch script

* Update readme

* Fix broken links and update quickstart

* Fix watch parameter

* Include README in watched files

* Make build script build everything

* Fix ci

* spellcheck

Author: acolytec3

.github/workflows/deploy.yaml

@@ -24,7 +24,7 @@ jobs:
         with:
           node-version: '22'
       - run: npm ci
-      - run: npm run build
+      - run: npm run build:spec
       - run: npm run build:docs
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v4

.github/workflows/test-deploy.yaml

@@ -4,8 +4,6 @@ on:
   pull_request:
     branches:
       - main
-    # Review gh actions docs if you want to further define triggers, paths, etc
-    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
   workflow_dispatch:
 
 jobs:
@@ -28,5 +26,5 @@ jobs:
         run: npm install --frozen-lockfile
       - name: Test build website
         run: |
-          npm run build
+          npm run build:spec
           npm run build:docs

.github/workflows/test.yaml

@@ -12,7 +12,7 @@ jobs:
         with:
           node-version: 22
       - run: npm ci
-      - run: npm run build
+      - run: npm run build:spec
       - run: npm run lint
       - name: Set up Go 1.x
         uses: actions/setup-go@v5

README.md

@@ -19,8 +19,9 @@ in [test-gen][test-gen]
 The specification itself is written in [OpenRPC][openrpc]. Refer to the OpenRPC
 specification and the JSON schema [specification][json-schema] to get started.
 
-### Building
+### Updating the specs
 
+#### Compiling
 The specification is split into multiple files to improve readability. The
 spec can be compiled into a single document as follows:
 
@@ -33,11 +34,26 @@ Build successful.
 This will output the file `openrpc.json` in the root of the project. This file
 will have all schema `#ref`s resolved.
 
-#### Testing
+#### Building the docs
+
+Once you've updated something in the spec, you can use the docs generation tools
+to view the updated specs locally.  
+
+```console
+$ npm run build:docs
+$ npm run watch
+```
+
+The `watch` command starts a local webserver serving the docs in-browser at 
+`http://0.0.0.0:8000` and it rebuilds when you update something in the specs.  
+Please reload the page to see your changes.
+
+### Testing
 
 There are several mechanisms for testing specification contributions and client
 conformance.
 
+#### Linting
 First is the [OpenRPC validator][validator]. It performs some basic syntactic
 checks on the generated specification.
 
@@ -47,13 +63,21 @@ $ npm run lint
 OpenRPC spec validated successfully.
 ```
 
+#### Spec tests
 Next is `speccheck`. This tool validates the test cases in the `tests`
-directory against the specification.
+directory against the specification.  There are two npm scripts to simplify this.
+
+```console
+$ npm run build:test
+$ npm run test 
+all passing.
+```
+
+or
 
 ```console
 $ go install github.com/lightclient/rpctestgen/cmd/speccheck@latest
 $ speccheck -v
-all passing.
 ```
 
 If you get an error that says: `speccheck: command not found`,
@@ -63,6 +87,8 @@ If you get an error that says: `speccheck: command not found`,
 $ export PATH=$HOME/go/bin:$PATH
 ```
 
+#### Spelling
+
 The spell checker ensures the specification is free of spelling errors.
 
 ```console
@@ -75,8 +101,9 @@ pyspelling is a wrapper around either [Aspell](http://aspell.net/) or
 [Hunspell](https://hunspell.github.io/). You'll need to install
 one of those before running `pyspelling`.
 
+#### Hive tests
 Finally, the test cases in the `tests/` directory may be run against individual
-execution client using the [`hive`] simulator [`rpc-compat`][rpc-compat].
+execution client using the [`hive`][hive] simulator [`rpc-compat`][rpc-compat].
 Please see the documentation in the aforementioned repositories for more
 information.
 

docs/reference/quickstart.md

@@ -19,8 +19,9 @@ in [test-gen][test-gen]
 The specification itself is written in [OpenRPC][openrpc]. Refer to the OpenRPC
 specification and the JSON schema [specification][json-schema] to get started.
 
-### Building
+### Updating the specs
 
+#### Compiling
 The specification is split into multiple files to improve readability. The
 spec can be compiled into a single document as follows:
 
@@ -33,11 +34,26 @@ Build successful.
 This will output the file `openrpc.json` in the root of the project. This file
 will have all schema `#ref`s resolved.
 
-#### Testing
+#### Building the docs
+
+Once you've updated something in the spec, you can use the docs generation tools
+to view the updated specs locally.  
+
+```console
+$ npm run build:docs
+$ npm run watch
+```
+
+The `watch` command starts a local webserver serving the docs in-browser at 
+`http://0.0.0.0:8000` and it rebuilds when you update something in the specs.  
+Please reload the page to see your changes.
+
+### Testing
 
 There are several mechanisms for testing specification contributions and client
 conformance.
 
+#### Linting
 First is the [OpenRPC validator][validator]. It performs some basic syntactic
 checks on the generated specification.
 
@@ -47,13 +63,21 @@ $ npm run lint
 OpenRPC spec validated successfully.
 ```
 
+#### Spec tests
 Next is `speccheck`. This tool validates the test cases in the `tests`
-directory against the specification.
+directory against the specification.  There are two npm scripts to simplify this.
+
+```console
+$ npm run build:test
+$ npm run test 
+all passing.
+```
+
+or
 
 ```console
 $ go install github.com/lightclient/rpctestgen/cmd/speccheck@latest
 $ speccheck -v
-all passing.
 ```
 
 If you get an error that says: `speccheck: command not found`,
@@ -63,6 +87,8 @@ If you get an error that says: `speccheck: command not found`,
 $ export PATH=$HOME/go/bin:$PATH
 ```
 
+#### Spelling
+
 The spell checker ensures the specification is free of spelling errors.
 
 ```console
@@ -75,8 +101,9 @@ pyspelling is a wrapper around either [Aspell](http://aspell.net/) or
 [Hunspell](https://hunspell.github.io/). You'll need to install
 one of those before running `pyspelling`.
 
+#### Hive tests
 Finally, the test cases in the `tests/` directory may be run against individual
-execution client using the [`hive`] simulator [`rpc-compat`][rpc-compat].
+execution client using the [`hive`][hive] simulator [`rpc-compat`][rpc-compat].
 Please see the documentation in the aforementioned repositories for more
 information.
 
@@ -104,16 +131,17 @@ $ npm run graphql:validate
 
 ## License
 
-This repository is licensed under [CC0](LICENSE).
+This repository is licensed under [CC0][license].
 
 
 [playground]: https://ethereum.github.io/execution-apis/api-documentation/
 [openrpc]: https://open-rpc.org
 [validator]: https://open-rpc.github.io/schema-utils-js/functions/validateOpenRPCDocument.html
 [graphql-schema]: http://graphql-schema.ethdevops.io/?url=https://raw.githubusercontent.com/ethereum/execution-apis/main/graphql.json
 [eip-1767]: https://eips.ethereum.org/EIPS/eip-1767
-[contributors-guide]: docs/reference/contributors-guide.md
+[contributors-guide]: ../contributors-guide
 [json-schema]: https://json-schema.org
 [hive]: https://github.com/ethereum/hive
 [rpc-compat]: https://github.com/ethereum/hive/tree/master/simulators/ethereum/rpc-compat
-[test-gen]: docs/reference/tests.md
+[test-gen]: ../tests
+[license]: https://github.com/ethereum/execution-apis/blob/main/LICENSE

docs/reference/tests.md

@@ -4,7 +4,7 @@ The Execution API has a comprehensive test suite to verify conformance of
 clients. The tests in this repository are loaded into the [`hive`][hive] test
 simulator [`rpc-compat`][rpc-compat] and validated against every major client.
 
-The test suite is run daily and results are always available [here][hivetests2]
+The test suite is run daily and results are always available [here][hivetests]
 under the tag `rpc-compat`. 
 
 To learn more about the `rpc-compat` simulator, please see its
@@ -68,6 +68,6 @@ A good final verification of tests is to run them in the hive simulator
 simulator can be found with there.
 
 [hive]: https://github.com/ethereum/hive
-[hivetests2]: https://hivetests2.ethdevops.io
+[hivetests]: https://hive.ethpandaops.io
 [rpc-compat]: https://github.com/ethereum/hive/tree/master/simulators/ethereum/rpc-compat
 [rpctestgen]: https://github.com/lightclient/rpctestgen