Skip to content

Commit 3779ff9

Browse files
acolytec3lightclient
acolytec3
and
lightclient
authored
Migrate docs to docusaurus (#653)
* add docusaurus * update deploy scripts * clean up stuff * update action * workflow dispatch trigger * build against main * push build to correct place * use correct working directory * fix references * update build artifact path in deploy workflow * consolidate in base dir * more cleanup * add test deploy ci * add workflow_dispatch * fix deploy script * build specs and website * don't throw on broken links * update baseUrl * make ESM/CJS stuff play nice * clean up links and docusaurus references * more link cleanup * update links to point to ethereum * remove docu boilerplate * build docs too * Update docs/reference/intro.md Co-authored-by: lightclient <[email protected]> * Update docusaurus.config.ts Co-authored-by: lightclient <[email protected]> * remove old deployment job * remove gatsby --------- Co-authored-by: lightclient <[email protected]> Co-authored-by: lightclient <[email protected]>
1 parent 15399c2 commit 3779ff9

File tree

16 files changed

+33122
-33072
lines changed

16 files changed

+33122
-33072
lines changed

‎.github/workflows/deploy.yaml‎

Lines changed: 39 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,53 @@
1-
name: Deploy specification
1+
name: Deploy to GitHub Pages
22

33
on:
44
push:
55
branches:
66
- main
7-
8-
env:
9-
# this avoids node running out of memory while building
10-
NODE_OPTIONS: --max_old_space_size=20480
7+
workflow_dispatch:
118

129
jobs:
13-
deploy-spec:
10+
build:
11+
name: Build Docusaurus
1412
runs-on: ubuntu-latest
1513
steps:
16-
- uses: actions/checkout@v2
17-
- name: Use Node.js 15
18-
uses: actions/setup-node@v1
14+
- uses: actions/checkout@v4
1915
with:
20-
node-version: '15'
21-
- run: npm ci
22-
- run: npm run build
23-
- name: setup git config
24-
run: |
25-
git config user.name "GitHub Actions Bot"
26-
git config user.email "<>"
27-
- name: Deploy assembled spec
16+
fetch-depth: 0
17+
- uses: actions/setup-node@v4
18+
with:
19+
node-version: 20
20+
cache: npm
21+
22+
- name: Install dependencies
23+
run: npm install --frozen-lockfile
24+
25+
- name: Build specs and website
2826
run: |
29-
git checkout -b assembled-spec
30-
git add -f openrpc.json
31-
git add -f refs-openrpc.json
32-
git commit -m "assemble openrpc.json"
33-
git push -fu origin assembled-spec
34-
deploy-gh-pages:
27+
npm run build
28+
npm run build:docs
29+
30+
- name: Upload Build Artifact
31+
uses: actions/upload-pages-artifact@v3
32+
with:
33+
path: build
34+
35+
deploy:
36+
name: Deploy to GitHub Pages
37+
needs: build
38+
39+
# Grant GITHUB_TOKEN the permissions required to make a Pages deployment
40+
permissions:
41+
pages: write # to deploy to Pages
42+
id-token: write # to verify the deployment originates from an appropriate source
43+
44+
# Deploy to the github-pages environment
45+
environment:
46+
name: github-pages
47+
url: ${{ steps.deployment.outputs.page_url }}
48+
3549
runs-on: ubuntu-latest
3650
steps:
37-
- uses: actions/checkout@v2
38-
- name: Use Node.js 15
39-
uses: actions/setup-node@v1
40-
with:
41-
node-version: '15'
42-
- run: npm ci
43-
- run: npm run build
44-
- run: npm run generate-clients
45-
- run: 'sed -i -e "s|Prefix: \"\"|Prefix: \"/execution-apis\"|g" build/docs/gatsby/gatsby-config.js'
46-
- run: 'sed -i -e "s|/api|api|g" build/docs/gatsby/src/pages/index.tsx'
47-
- run: npm run build:docs
48-
- name: setup git config
49-
run: |
50-
git config user.name "GitHub Actions Bot"
51-
git config user.email "<>"
5251
- name: Deploy to GitHub Pages
53-
if: success()
54-
uses: crazy-max/ghaction-github-pages@v3
55-
with:
56-
target_branch: gh-pages
57-
build_dir: build/docs/gatsby/public
58-
env:
59-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
52+
id: deployment
53+
uses: actions/deploy-pages@v4

‎.github/workflows/test-deploy.yaml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: Test deployment
2+
3+
on:
4+
pull_request:
5+
branches:
6+
- main
7+
# Review gh actions docs if you want to further define triggers, paths, etc
8+
# https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
9+
workflow_dispatch:
10+
11+
jobs:
12+
test-deploy:
13+
name: Test deployment
14+
runs-on: ubuntu-latest
15+
steps:
16+
- uses: actions/checkout@v4
17+
with:
18+
fetch-depth: 0
19+
- uses: actions/setup-node@v4
20+
with:
21+
node-version: 20
22+
cache: npm
23+
24+
- name: Install dependencies
25+
run: npm install --frozen-lockfile
26+
- name: Test build website
27+
run: |
28+
npm run build
29+
npm run build:docs

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,4 @@ data.json
77
schema.json
88
*.dic
99
.idea/
10+
.docusaurus

‎.nojekyll‎

Whitespace-only changes.

‎css/custom.css‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
/**
2+
* Any CSS included here will be global. The classic template
3+
* bundles Infima by default. Infima is a CSS framework designed to
4+
* work well for content-centric websites.
5+
*/
6+
7+
/* You can override the default Infima variables here. */
8+
:root {
9+
--ifm-color-primary: #2e8555;
10+
--ifm-color-primary-dark: #29784c;
11+
--ifm-color-primary-darker: #277148;
12+
--ifm-color-primary-darkest: #205d3b;
13+
--ifm-color-primary-light: #33925d;
14+
--ifm-color-primary-lighter: #359962;
15+
--ifm-color-primary-lightest: #3cad6e;
16+
--ifm-code-font-size: 95%;
17+
--docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
18+
}
19+
20+
/* For readability concerns, you should choose a lighter palette in dark mode. */
21+
[data-theme='dark'] {
22+
--ifm-color-primary: #25c2a0;
23+
--ifm-color-primary-dark: #21af90;
24+
--ifm-color-primary-darker: #1fa588;
25+
--ifm-color-primary-darkest: #1a8870;
26+
--ifm-color-primary-light: #29d5b0;
27+
--ifm-color-primary-lighter: #32d8b4;
28+
--ifm-color-primary-lightest: #4fddbf;
29+
--docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
30+
}

‎docs/reference/intro.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
slug: /
3+
sidebar_position: 1
4+
---
5+
6+
# Introduction
7+
8+
Welcome to the Ethereum JSON-RPC documentation. This site provides comprehensive information about the JSON-RPC APIs provided by Ethereum execution clients.
9+
10+
## What are Execution APIs?
11+
12+
Execution APIs are the set of JSON-RPC endpoints that allow applications to interact with Ethereum nodes. These APIs enable developers to:
13+
14+
- Query blockchain data
15+
- Send transactions
16+
- Interact with smart contracts
17+
- Monitor network status
18+
- And much more
19+
20+
## Getting Started
21+
22+
To get started with the Execution APIs:
23+
24+
1. Choose an Ethereum client implementation
25+
2. Set up your development environment
26+
3. Connect to an Ethereum node
27+
4. Start making JSON-RPC calls
28+
29+
## API Categories
30+
31+
The Execution APIs are organized into several categories:
32+
33+
- Core APIs
34+
- Account APIs
35+
- Network APIs
36+
- Debug APIs
37+
- Trace APIs
38+
39+
Each category serves specific purposes and provides different functionalities for interacting with the Ethereum network.
40+
41+
## Contributing
42+
43+
We welcome contributions to improve this documentation. Please see our [Making Changes](/reference/making-changes) guide for more information on how to contribute.

‎docs/making-changes.md‎ renamed to ‎docs/reference/making-changes.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -115,4 +115,4 @@ others don't.
115115

116116
[exec-apis]: https://github.com/ethereum/execution-apis
117117
[pm]: https://github.com/ethereum/pm
118-
[test-gen]: ../tests/README.md
118+
[test-gen]: https://github.com/ethereum/execution-apis/blob/main/tests/README.md

‎docusaurus.config.ts‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
import { themes as prismThemes } from 'prism-react-renderer';
2+
import type { Config } from '@docusaurus/types';
3+
import type * as Preset from '@metamask/docusaurus-openrpc/dist/preset';
4+
5+
// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
6+
7+
const config: Config = {
8+
title: 'Ethereum Execution APIs',
9+
tagline: 'A JSON-RPC specification for Ethereum execution clients',
10+
favicon: 'img/favicon.ico',
11+
12+
// Set the production url of your site here
13+
url: 'https://ethereum.github.io',
14+
// Set the /<baseUrl>/ pathname under which your site is served
15+
// For GitHub pages deployment, it is often '/<projectName>/'
16+
baseUrl: '/execution-apis/',
17+
18+
// GitHub pages deployment config.
19+
// If you aren't using GitHub pages, you don't need these.
20+
organizationName: 'ethereum', // Usually your GitHub org/user name.
21+
projectName: 'execution-apis', // Usually your repo name.
22+
deploymentBranch: 'gh-pages',
23+
24+
onBrokenLinks: 'warn',
25+
onBrokenMarkdownLinks: 'warn',
26+
27+
// Even if you don't use internationalization, you can use this field to set
28+
// useful metadata like html lang. For example, if your site is Chinese, you
29+
// may want to replace "en" with "zh-Hans".
30+
i18n: {
31+
defaultLocale: 'en',
32+
locales: ['en'],
33+
},
34+
35+
presets: [
36+
[
37+
'@metamask/docusaurus-openrpc/dist/preset',
38+
/** @type {import('@metamask/docusaurus-openrpc/dist/preset').Options} */
39+
{
40+
docs: {
41+
routeBasePath: '/',
42+
openrpc: {
43+
openrpcDocument: './refs-openrpc.json',
44+
path: 'reference',
45+
sidebarLabel: 'JSON-RPC',
46+
},
47+
sidebarPath: './sidebars.ts',
48+
path: './docs',
49+
},
50+
blog: false,
51+
theme: {
52+
customCss: './css/custom.css',
53+
},
54+
} satisfies Preset.Options,
55+
],
56+
],
57+
58+
themeConfig: {
59+
// Replace with your project's social card
60+
image: 'img/docusaurus-social-card.jpg',
61+
navbar: {
62+
title: 'Execution APIs',
63+
// logo: {
64+
// alt: 'My Site Logo',
65+
// src: 'img/logo.svg',
66+
// },
67+
items: [
68+
{
69+
type: 'docSidebar',
70+
sidebarId: 'referenceSidebar',
71+
position: 'left',
72+
label: 'API Reference',
73+
},
74+
{
75+
href: 'https://github.com/ethereum/execution-apis',
76+
label: 'GitHub',
77+
position: 'right',
78+
},
79+
],
80+
},
81+
footer: {
82+
style: 'dark',
83+
links: [
84+
{
85+
title: 'More',
86+
items: [
87+
{
88+
label: 'GitHub',
89+
href: 'https://github.com/ethereum/execution-apis',
90+
},
91+
],
92+
},
93+
],
94+
copyright: `Copyright and related rights waived via CC0.`,
95+
},
96+
prism: {
97+
theme: prismThemes.github,
98+
darkTheme: prismThemes.dracula,
99+
},
100+
} satisfies Preset.ThemeConfig,
101+
};
102+
103+
export default config;

0 commit comments

Comments
 (0)