Merge branch 'main' into no-history-error-simple

Author: fjl

.github/workflows/deploy.yaml

@@ -1,59 +1,34 @@
-name: Deploy specification
+name: Deploy to GitHub Pages
 
 on:
   push:
     branches:
       - main
+  workflow_dispatch:
 
 env:
-  # this avoids node running out of memory while building
-  NODE_OPTIONS: --max_old_space_size=20480
+  GITHUB_REPOSITORY: ${{ github.repository }}
 
 jobs:
-  deploy-spec:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - name: Use Node.js 15
-        uses: actions/setup-node@v1
-        with:
-          node-version: '15'
-      - run: npm ci
-      - run: npm run build
-      - name: setup git config
-        run: |
-          git config user.name "GitHub Actions Bot"
-          git config user.email "<>"
-      - name: Deploy assembled spec
-        run: |
-          git checkout -b assembled-spec
-          git add -f openrpc.json
-          git add -f refs-openrpc.json
-          git commit -m "assemble openrpc.json"
-          git push -fu origin assembled-spec
   deploy-gh-pages:
+    permissions:
+      pages: write
+      id-token: write
+      contents: write
+
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - name: Use Node.js 15
-        uses: actions/setup-node@v1
+      - uses: actions/checkout@v4
+      - name: Use Node.js 22
+        uses: actions/setup-node@v4
         with:
-          node-version: '15'
+          node-version: '22'
       - run: npm ci
-      - run: npm run build
-      - run: npm run generate-clients
-      - run: 'sed -i -e "s|Prefix: \"\"|Prefix: \"/execution-apis\"|g" build/docs/gatsby/gatsby-config.js'
-      - run: 'sed -i -e "s|/api|api|g" build/docs/gatsby/src/pages/index.tsx'
+      - run: npm run build:spec
       - run: npm run build:docs
-      - name: setup git config
-        run: |
-          git config user.name "GitHub Actions Bot"
-          git config user.email "<>"
       - name: Deploy to GitHub Pages
-        if: success()
-        uses: crazy-max/ghaction-github-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
-          target_branch: gh-pages
-          build_dir: build/docs/gatsby/public
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: build/docs/gatsby/public
+          commit_message: "Deploy to GitHub Pages"

.github/workflows/test-deploy.yaml

@@ -0,0 +1,30 @@
+name: Test deployment
+
+on:
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  test-deploy:
+    name: Test deployment
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 22, 24]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+
+      - name: Install dependencies
+        run: npm install --frozen-lockfile
+      - name: Test build website
+        run: |
+          npm run build:spec
+          npm run build:docs

.github/workflows/test.yaml

@@ -6,16 +6,16 @@ jobs:
   lint-and-check:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - name: Use Node.js 15.x
-        uses: actions/setup-node@v1
+      - uses: actions/checkout@v4
+      - name: Use Node.js 22
+        uses: actions/setup-node@v4
         with:
-          node-version: ^15.x
+          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@v2
+        uses: actions/setup-go@v5
         with:
           go-version: ^1.18
         id: go

.gitignore

@@ -6,3 +6,4 @@ refs-openrpc.json
 data.json
 schema.json
 *.dic
+.idea/

.nojekyll

@@ -11,17 +11,18 @@ Ethereum clients as modules that can be swapped at will.
 
 ### Contributing
 
-Please see the contributors guide in [`docs/making-changes.md`][making-changes]
+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.
 
-### Building
+### Updating the specs
 
-The specification is split into multiple files to improve readability. The 
+#### Compiling
+The specification is split into multiple files to improve readability. The
 spec can be compiled into a single document as follows:
 
 ```console
@@ -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. 
+conformance.
 
+#### Linting
 First is the [OpenRPC validator][validator]. It performs some basic syntactic
 checks on the generated specification.
 
@@ -47,15 +63,32 @@ $ 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`,
+ make sure that the go binary is in your $PATH:
+
+```console
+$ export PATH=$HOME/go/bin:$PATH
+```
+
+#### Spelling
+
 The spell checker ensures the specification is free of spelling errors.
 
 ```console
@@ -64,8 +97,13 @@ $ 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`.
+
+#### 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.
 
@@ -101,8 +139,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
-[making-changes]: docs/making-changes.md
-[json-schema]: https://json-schema.org 
+[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

README.md

@@ -0,0 +1,82 @@
+const remarkGfm = require('remark-gfm');
+
+module.exports = {
+  pathPrefix: "/execution-apis",
+  siteMetadata: {
+    title: 'Ethereum JSON-RPC Specification',
+    description: 'A specification of the standard interface for Ethereum clients.',
+    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',
+    primaryColor: '#3f51b5', //material-ui primary color
+    secondaryColor: '#f50057', //material-ui secondary color
+    author: '',
+    menuLinks: [
+      { 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: [
+      {
+        name: 'OpenRPC',
+        link: 'https://open-rpc.org'
+      }
+    ]
+  },
+  plugins: [
+   {
+      resolve: 'gatsby-plugin-mdx',
+      options: {
+        extensions: ['.mdx', '.md'],
+        gatsbyRemarkPlugins: [
+          {
+            resolve: 'gatsby-remark-autolink-headers',
+            options: {
+              icon: false,
+            },
+          },
+        ],
+        mdxOptions: {
+          remarkPlugins: [remarkGfm],
+        },
+      },
+    },
+    "gatsby-openrpc-theme",
+    {
+      resolve: 'gatsby-plugin-manifest',
+      options: {
+        name: 'pristine-site',
+        short_name: 'pristine-site',
+        start_url: '/execution-apis/',
+        background_color: 'transparent',
+        theme_color: '#3f51b5',
+        display: 'minimal-ui',
+        icon: 'src/images/gatsby-icon.png', // This path is relative to the root of the site.
+      },
+    },
+    "gatsby-plugin-image",
+    "gatsby-plugin-sharp",
+    "gatsby-transformer-sharp",
+    {
+      resolve: "gatsby-source-filesystem",
+      options: {
+        name: "images",
+        path: __dirname + '/src/images',
+      },
+    },
+    {
+      resolve: "gatsby-source-filesystem",
+      options: {
+        name: "docs",
+        path: __dirname + '/../../../docs/reference',
+      },
+    },
+  ],
+}

docs/config/gatsby-config.js

@@ -115,4 +115,4 @@ others don't.
 
 [exec-apis]: https://github.com/ethereum/execution-apis
 [pm]: https://github.com/ethereum/pm
-[test-gen]: ../tests/README.md
+[test-gen]: https://github.com/ethereum/execution-apis/blob/main/docs/reference/tests.md