Fix broken links and update quickstart

Author: acolytec3

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/docs/reference/json-rpc-api
 [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

package.json

@@ -16,7 +16,7 @@
     "graphql:validate": "node scripts/graphql-validate.js",
     "serve": "cd build/docs/gatsby && gatsby develop",
     "test": "speccheck -v",
-    "watch": "nodemon --watch src --ext yaml,md,json --exec \"npm run build && cp ./openrpc.json build/docs/gatsby/src/openrpc.json && npm run serve\""
+    "watch": "nodemon --watch src,docs --ext yaml,md,json --exec \"npm run build && cp ./openrpc.json build/docs/gatsby/src/openrpc.json && npm run serve\""
   },
   "repository": {
     "type": "git",