Clean up links and add tests/quickstart to docs

Author: acolytec3

README.md

@@ -11,10 +11,10 @@ Ethereum clients as modules that can be swapped at will.
 
 ### Contributing
 
-Please see the contributors guide in [`docs/contributors-guide.md`][contributors-guide]
+Please see the [contributors guide][contributors-guide]
 for general information about the process of standardizing new API methods and
 making changes to existing ones. Information on test generation can be found
-in [`tests/README.md`][test-gen]
+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.
@@ -112,8 +112,8 @@ This repository is licensed under [CC0](LICENSE).
 [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/contributors-guide.md
+[contributors-guide]: docs/reference/contributors-guide.md
 [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]: tests/README.md
+[test-gen]: docs/reference/tests.md

docs/config/gatsby-config.js

@@ -13,12 +13,14 @@ module.exports = {
     secondaryColor: '#f50057', //material-ui secondary color
     author: '',
     menuLinks: [
-      { name: 'Introduction', link: '/introduction' },
+      { name: 'Introduction', link: '/intro' },
       {
         name: 'API Documentation',
         link: '/api-documentation'
       },
+      { name: 'Quickstart', link: '/quickstart' },
       { name: 'Contributors Guide', link: '/contributors-guide' },
+      { name: 'Testing', link: '/tests'},
       { name: 'Ethsimulatev1 notes', link: '/ethsimulatev1-notes' },
     ],
     footerLinks: [

docs/reference/quickstart.md

@@ -0,0 +1,119 @@
+# Execution API Specification
+
+## JSON-RPC
+
+[View the spec][playground]
+
+The Ethereum JSON-RPC is a standard collection of methods that all execution
+clients implement. It is the canonical interface between users and the network.
+This interface allows downstream tooling and infrastructure to treat different
+Ethereum clients as modules that can be swapped at will.
+
+### Contributing
+
+Please see the [contributors guide][contributors-guide]
+for general information about the process of standardizing new API methods and
+making changes to existing ones. Information on test generation can be found
+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
+
+The specification is split into multiple files to improve readability. The
+spec can be compiled into a single document as follows:
+
+```console
+$ npm install
+$ npm run build
+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
+
+There are several mechanisms for testing specification contributions and client
+conformance.
+
+First is the [OpenRPC validator][validator]. It performs some basic syntactic
+checks on the generated specification.
+
+```console
+$ npm install
+$ npm run lint
+OpenRPC spec validated successfully.
+```
+
+Next is `speccheck`. This tool validates the test cases in the `tests`
+directory against the specification.
+
+```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`,
+ make sure that the go binary is in your $PATH:
+
+```console
+$ export PATH=$HOME/go/bin:$PATH
+```
+
+The spell checker ensures the specification is free of spelling errors.
+
+```console
+$ pip install pyspelling
+$ pyspelling -c spellcheck.yaml
+Spelling check passed :)
+```
+
+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`.
+
+Finally, the test cases in the `tests/` directory may be run against individual
+execution client using the [`hive`] simulator [`rpc-compat`][rpc-compat].
+Please see the documentation in the aforementioned repositories for more
+information.
+
+## GraphQL
+
+[View the spec][graphql-schema]
+
+[EIP-1767][eip-1767] proposed a GraphQL schema for interacting with Ethereum clients. Since then Besu and Geth have implemented the interface. This repo contains a live specification to integrate changes to the protocol as well as other improvements into the GraphQL schema.
+
+### Generation
+
+The schema in this repo is generated by issuing a meta GraphQL query against a live node. This can be done as follows:
+
+```console
+$ npm run graphql:schema
+```
+
+### Testing
+
+A script is included in the source code which reads and validates the given schema to be a valid one. It is recommended to perform this check after modifying the schema by:
+
+```console
+$ npm run graphql:validate
+```
+
+## 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
+[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

tests/README.md renamed to docs/reference/tests.md

@@ -7,7 +7,7 @@
     "build": "npm run build:spec",
     "build:spec": "node scripts/build.js",
     "build:docs": "npm run generate-clients && npm run build:docs:gatsby",
-    "build:docs:gatsby": "cd build/docs/gatsby && npm install && gatsby build --prefix-paths",
+    "build:docs:gatsby": "cp README.md docs/reference/quickstart.md && cd build/docs/gatsby && npm install && gatsby build --prefix-paths",
     "lint": "node scripts/build.js && node scripts/validate.js && node scripts/graphql-validate.js",
     "clean": "rm -rf build && mkdir -p build",
     "generate-clients": "mkdir -p build && open-rpc-generator generate -c open-rpc-generator-config.json",
@@ -46,4 +46,4 @@
     "react": "^18.0.0",
     "react-dom": "^18.0.0"
   }
-}
+}