Implement JSON-RPC API namespace separation in documentation

Author: bomanaps

docs/reference/json-rpc/debug-namespace.md

@@ -0,0 +1,13 @@
+---
+sidebar_position: 1
+---
+
+# Debug Namespace
+
+This page lists all JSON-RPC methods in the debug namespace.
+
+- [debug_getBadBlocks](/reference/debug_getBadBlocks)
+- [debug_getRawBlock](/reference/debug_getRawBlock)
+- [debug_getRawHeader](/reference/debug_getRawHeader)
+- [debug_getRawReceipts](/reference/debug_getRawReceipts)
+- [debug_getRawTransaction](/reference/debug_getRawTransaction)

docs/reference/json-rpc/engine-namespace.md

@@ -0,0 +1,26 @@
+---
+sidebar_position: 1
+---
+
+# Engine Namespace
+
+This page lists all JSON-RPC methods in the engine namespace.
+
+- [engine_exchangeCapabilities](/reference/engine_exchangeCapabilities)
+- [engine_exchangeTransitionConfigurationV1](/reference/engine_exchangeTransitionConfigurationV1)
+- [engine_forkchoiceUpdatedV1](/reference/engine_forkchoiceUpdatedV1)
+- [engine_forkchoiceUpdatedV2](/reference/engine_forkchoiceUpdatedV2)
+- [engine_forkchoiceUpdatedV3](/reference/engine_forkchoiceUpdatedV3)
+- [engine_getBlobsV1](/reference/engine_getBlobsV1)
+- [engine_getBlobsV2](/reference/engine_getBlobsV2)
+- [engine_getPayloadBodiesByHashV1](/reference/engine_getPayloadBodiesByHashV1)
+- [engine_getPayloadBodiesByRangeV1](/reference/engine_getPayloadBodiesByRangeV1)
+- [engine_getPayloadV1](/reference/engine_getPayloadV1)
+- [engine_getPayloadV2](/reference/engine_getPayloadV2)
+- [engine_getPayloadV3](/reference/engine_getPayloadV3)
+- [engine_getPayloadV4](/reference/engine_getPayloadV4)
+- [engine_getPayloadV5](/reference/engine_getPayloadV5)
+- [engine_newPayloadV1](/reference/engine_newPayloadV1)
+- [engine_newPayloadV2](/reference/engine_newPayloadV2)
+- [engine_newPayloadV3](/reference/engine_newPayloadV3)
+- [engine_newPayloadV4](/reference/engine_newPayloadV4)

docs/reference/json-rpc/eth-namespace.md

@@ -0,0 +1,47 @@
+---
+sidebar_position: 1
+---
+
+# ETH Namespace
+
+This page lists all JSON-RPC methods in the eth namespace.
+
+- [eth_accounts](/reference/eth_accounts)
+- [eth_blobBaseFee](/reference/eth_blobBaseFee)
+- [eth_blockNumber](/reference/eth_blockNumber)
+- [eth_call](/reference/eth_call)
+- [eth_chainId](/reference/eth_chainId)
+- [eth_coinbase](/reference/eth_coinbase)
+- [eth_createAccessList](/reference/eth_createAccessList)
+- [eth_estimateGas](/reference/eth_estimateGas)
+- [eth_feeHistory](/reference/eth_feeHistory)
+- [eth_gasPrice](/reference/eth_gasPrice)
+- [eth_getBalance](/reference/eth_getBalance)
+- [eth_getBlockByHash](/reference/eth_getBlockByHash)
+- [eth_getBlockByNumber](/reference/eth_getBlockByNumber)
+- [eth_getBlockReceipts](/reference/eth_getBlockReceipts)
+- [eth_getBlockTransactionCountByHash](/reference/eth_getBlockTransactionCountByHash)
+- [eth_getBlockTransactionCountByNumber](/reference/eth_getBlockTransactionCountByNumber)
+- [eth_getCode](/reference/eth_getCode)
+- [eth_getFilterChanges](/reference/eth_getFilterChanges)
+- [eth_getFilterLogs](/reference/eth_getFilterLogs)
+- [eth_getLogs](/reference/eth_getLogs)
+- [eth_getProof](/reference/eth_getProof)
+- [eth_getStorageAt](/reference/eth_getStorageAt)
+- [eth_getTransactionByBlockHashAndIndex](/reference/eth_getTransactionByBlockHashAndIndex)
+- [eth_getTransactionByBlockNumberAndIndex](/reference/eth_getTransactionByBlockNumberAndIndex)
+- [eth_getTransactionByHash](/reference/eth_getTransactionByHash)
+- [eth_getTransactionCount](/reference/eth_getTransactionCount)
+- [eth_getTransactionReceipt](/reference/eth_getTransactionReceipt)
+- [eth_getUncleCountByBlockHash](/reference/eth_getUncleCountByBlockHash)
+- [eth_getUncleCountByBlockNumber](/reference/eth_getUncleCountByBlockNumber)
+- [eth_maxPriorityFeePerGas](/reference/eth_maxPriorityFeePerGas)
+- [eth_newBlockFilter](/reference/eth_newBlockFilter)
+- [eth_newFilter](/reference/eth_newFilter)
+- [eth_newPendingTransactionFilter](/reference/eth_newPendingTransactionFilter)
+- [eth_sendRawTransaction](/reference/eth_sendRawTransaction)
+- [eth_sendTransaction](/reference/eth_sendTransaction)
+- [eth_sign](/reference/eth_sign)
+- [eth_signTransaction](/reference/eth_signTransaction)
+- [eth_syncing](/reference/eth_syncing)
+- [eth_uninstallFilter](/reference/eth_uninstallFilter)

docs/reference/json-rpc/introduction.md

@@ -0,0 +1,13 @@
+---
+sidebar_position: 1
+---
+
+# JSON-RPC API Introduction
+
+The Ethereum JSON-RPC API is organized into several namespaces, each containing related methods:
+
+- [Debug Namespace](/reference/json-rpc/debug-namespace)
+- [Engine Namespace](/reference/json-rpc/engine-namespace)
+- [Eth Namespace](/reference/json-rpc/eth-namespace)
+
+Each namespace contains methods with specific functionality related to different aspects of Ethereum node operation.

package.json

@@ -6,14 +6,15 @@
   "scripts": {
     "build": "npm run build:spec",
     "build:spec": "node scripts/build.mjs",
+    "build:namespaced-sidebars": "node scripts/generateNamespacedSidebars.mjs",
     "lint": "npm run build:spec && node scripts/validate.mjs && node scripts/graphql-validate.mjs",
     "clean": "rm -rf build && mkdir -p build",
     "generate-clients": "mkdir -p build && open-rpc-generator generate -c open-rpc-generator-config.json",
     "graphql:schema": "node scripts/graphql.mjs",
     "graphql:validate": "node scripts/graphql-validate.mjs",
     "docusaurus": "docusaurus",
-    "start:docs": "docusaurus start",
-    "build:docs": "docusaurus build",
+    "start:docs": "npm run build:spec && npm run build:namespaced-sidebars && docusaurus start",
+    "build:docs": "npm run build:spec && npm run build:namespaced-sidebars && docusaurus build",
     "swizzle:docs": "docusaurus swizzle",
     "deploy:docs": "docusaurus deploy",
     "clear:docs": "docusaurus clear",

scripts/build.mjs

@@ -18,12 +18,21 @@ function sortByMethodName(methods) {
 console.log("Loading files...\n");
 
 let methods = [];
+// Create a separate map for method namespaces
+let methodNamespaces = {};
+
 let methodsBase = "src/eth/";
 let methodFiles = fs.readdirSync(methodsBase);
 methodFiles.forEach(file => {
   console.log(file);
   let raw = fs.readFileSync(methodsBase + file);
   let parsed = yaml.load(raw);
+  // Store namespace mapping separately
+  parsed.forEach(method => {
+    if (method.name) {
+      methodNamespaces[method.name] = 'eth';
+    }
+  });
   methods = [
     ...methods,
     ...parsed,
@@ -36,6 +45,12 @@ methodFiles.forEach(file => {
   console.log(file);
   let raw = fs.readFileSync(methodsBase + file);
   let parsed = yaml.load(raw);
+  // Store namespace mapping separately
+  parsed.forEach(method => {
+    if (method.name) {
+      methodNamespaces[method.name] = 'debug';
+    }
+  });
   methods = [
     ...methods,
     ...parsed,
@@ -48,6 +63,12 @@ methodFiles.forEach(file => {
   console.log(file);
   let raw = fs.readFileSync(methodsBase + file);
   let parsed = yaml.load(raw);
+  // Store namespace mapping separately
+  parsed.forEach(method => {
+    if (method.name) {
+      methodNamespaces[method.name] = 'engine';
+    }
+  });
   methods = [
     ...methods,
     ...parsed,
@@ -98,6 +119,9 @@ const doc = {
 
 fs.writeFileSync('refs-openrpc.json', JSON.stringify(doc, null, '\t'));
 
+// Save the method namespace mapping separately
+fs.writeFileSync('method-namespaces.json', JSON.stringify(methodNamespaces, null, '\t'));
+
 let spec = await dereferenceDocument(doc);
 
 spec.components = {};

scripts/generateNamespacedSidebars.mjs

@@ -0,0 +1,93 @@
+import fs from 'fs';
+
+/**
+ * Generates a namespaced sidebar configuration based on the OpenRPC document
+ */
+async function generateNamespacedSidebars() {
+  console.log('Generating namespaced sidebars...');
+
+  // Read the OpenRPC document
+  const openrpcData = JSON.parse(fs.readFileSync('refs-openrpc.json', 'utf8'));
+  
+  // Read the method namespaces mapping
+  const methodNamespaces = JSON.parse(fs.readFileSync('method-namespaces.json', 'utf8'));
+
+  // Group methods by namespace
+  const namespaces = {};
+  
+  openrpcData.methods.forEach(method => {
+    const methodName = method.name;
+    const namespace = methodNamespaces[methodName] || extractNamespace(methodName);
+    if (!namespaces[namespace]) {
+      namespaces[namespace] = [];
+    }
+    namespaces[namespace].push(methodName);
+  });
+
+  // Make sure directory exists
+  if (!fs.existsSync('docs/reference/json-rpc')) {
+    fs.mkdirSync('docs/reference/json-rpc', { recursive: true });
+  }
+
+  // Add custom JSON-RPC reference sidebar to docs
+  fs.writeFileSync('docs/reference/json-rpc/eth-namespace.md', generateSidebarPage('ETH Namespace', namespaces['eth'] || []));
+  fs.writeFileSync('docs/reference/json-rpc/debug-namespace.md', generateSidebarPage('Debug Namespace', namespaces['debug'] || []));
+  fs.writeFileSync('docs/reference/json-rpc/engine-namespace.md', generateSidebarPage('Engine Namespace', namespaces['engine'] || []));
+  
+  // Create a sidebar introduction page
+  fs.writeFileSync('docs/reference/json-rpc/introduction.md', generateIntroductionPage(Object.keys(namespaces)));
+  
+  console.log('Namespaced sidebar files generated successfully!');
+}
+
+/**
+ * Extracts namespace from method name (e.g., eth_blockNumber -> eth)
+ */
+function extractNamespace(methodName) {
+  if (!methodName) return 'other';
+  
+  const parts = methodName.split('_');
+  if (parts.length > 1) {
+    return parts[0];
+  }
+  
+  return 'other';
+}
+
+/**
+ * Generates a markdown page for a specific namespace
+ */
+function generateSidebarPage(title, methods) {
+  const sortedMethods = [...methods].sort();
+  
+  return `---
+sidebar_position: 1
+---
+
+# ${title}
+
+This page lists all JSON-RPC methods in the ${title.toLowerCase()}.
+
+${sortedMethods.map(method => `- [${method}](/reference/${method})`).join('\n')}
+`;
+}
+
+/**
+ * Generates an introduction page for JSON-RPC API
+ */
+function generateIntroductionPage(namespaces) {
+  return `---
+sidebar_position: 1
+---
+
+# JSON-RPC API Introduction
+
+The Ethereum JSON-RPC API is organized into several namespaces, each containing related methods:
+
+${namespaces.map(namespace => `- [${namespace.charAt(0).toUpperCase() + namespace.slice(1)} Namespace](/reference/json-rpc/${namespace}-namespace)`).join('\n')}
+
+Each namespace contains methods with specific functionality related to different aspects of Ethereum node operation.
+`;
+}
+
+generateNamespacedSidebars().catch(console.error); 

sidebars.ts

@@ -13,17 +13,51 @@ import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
  Create as many sidebars as you want.
  */
 const sidebars: SidebarsConfig = {
-  referenceSidebar: [{
-    type: "category",
-    label: "Reference",
-    link: { type: "generated-index" },
-    items: [
-      {
-        type: "autogenerated",
-        dirName: "reference",
-      }
-    ],
-  },],
+  referenceSidebar: [
+    {
+      type: "category",
+      label: "Reference",
+      link: { type: "generated-index" },
+      items: [
+        {
+          type: "doc",
+          id: "reference/intro",
+          label: "Introduction"
+        },
+        {
+          type: "doc",
+          id: "reference/making-changes",
+          label: "Contributors Guide"
+        },
+        {
+          type: "category",
+          label: "JSON-RPC API",
+          items: [
+            {
+              type: "doc",
+              id: "reference/json-rpc/introduction",
+              label: "Introduction",
+            },
+            {
+              type: "doc",
+              id: "reference/json-rpc/eth-namespace",
+              label: "ETH Namespace",
+            },
+            {
+              type: "doc",
+              id: "reference/json-rpc/debug-namespace",
+              label: "Debug Namespace",
+            },
+            {
+              type: "doc",
+              id: "reference/json-rpc/engine-namespace",
+              label: "Engine Namespace",
+            }
+          ]
+        }
+      ],
+    },
+  ],
 };
 
 export default sidebars;