Generating chain-specific documentation

.gitignore

@@ -1,2 +1,5 @@
 node_modules
-/docs/dist
+/docs/dist
+/chain_docs/dist
+/docs/pages/chains
+.papi

chain_docs/generate.ts

@@ -0,0 +1,65 @@
+import cp from "child_process"
+import fs from "fs"
+import path from "path"
+
+import { networks } from "./networks"
+
+/*
+  in process.env.NODE_ENV === "development", this script generates docs
+  in "./chain_docs/dist", which is served by a separate server
+
+  in process.env.NODE_ENV === "production", this script overwrites
+  "./docs/dist/chain_docs, expecting vocs generation to be executed prior
+ */
+
+const CHAIN_DOCS_DIST =
+  process.env.NODE_ENV === "development"
+    ? path.join(process.cwd(), "chain_docs", "dist")
+    : path.join(process.cwd(), "docs", "dist", "chains")
+
+const spawnAndWait = (cmd: string, args: string[]): Promise<void> =>
+  new Promise((resolve, reject) => {
+    const proc = cp.spawn(cmd, args, { stdio: "inherit", shell: true })
+    proc.on("exit", (code, signal) => {
+      if (code === 0) resolve()
+      else
+        reject(
+          `Process ${cmd} ${args} ` + signal === null
+            ? `exited with code ${code}`
+            : `killed with signal ${signal}`,
+        )
+    })
+  })
+
+;(async () => {
+  if (
+    process.env.NODE_ENV === "development" &&
+    fs.existsSync(CHAIN_DOCS_DIST)
+  ) {
+    console.log(
+      `${CHAIN_DOCS_DIST} dir already exists; skipping chain docs generation`,
+    )
+    process.exit(0)
+  }
+
+  for (const network of Object.keys(networks)) {
+    if (
+      !fs.existsSync(
+        path.join(process.cwd(), ".papi", "metadata", `${network}.scale`),
+      )
+    ) {
+      await spawnAndWait(
+        path.join(process.cwd(), "node_modules", ".bin", "papi"),
+        ["add", "--skip-codegen", "-n", network, network],
+      )
+    }
+  }
+
+  await spawnAndWait(
+    path.join(process.cwd(), "node_modules", ".bin", "papi-generate-docs"),
+    ["--output", CHAIN_DOCS_DIST],
+  )
+})().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})

chain_docs/networks.ts

@@ -0,0 +1,58 @@
+export const networks = {
+  polkadot: "Polkadot",
+  polkadot_asset_hub: "Polkadot Asset Hub",
+  polkadot_bridge_hub: "Polkadot Brigde Hub",
+  polkadot_collectives: "Polkadot Collectives",
+  polkadot_people: "Polkadot People",
+  ksmcc3: "Kusama",
+  ksmcc3_asset_hub: "Kusama Asset Hub",
+  ksmcc3_bridge_hub: "Kusama Brigde Hub",
+  ksmcc3_people: "Kusama People",
+  ksmcc3_encointer: "Encointer",
+  paseo: "Paseo",
+  paseo_asset_hub: "Paseo Asset Hub",
+  westend2: "Westend",
+  westend2_asset_hub: "Westend Asset Hub",
+  westend2_bridge_hub: "Westend Brigde Hub",
+  westend2_collectives: "Westend Collectives",
+  westend2_people: "Westend People",
+} as const
+
+type Network = keyof typeof networks
+
+export const sections: { text: string; items: Network[] }[] = [
+  {
+    text: "Polkadot and parachains",
+    items: [
+      "polkadot",
+      "polkadot_asset_hub",
+      "polkadot_bridge_hub",
+      "polkadot_collectives",
+      "polkadot_people",
+    ],
+  },
+  {
+    text: "Kusama and parachains",
+    items: [
+      "ksmcc3",
+      "ksmcc3_asset_hub",
+      "ksmcc3_bridge_hub",
+      "ksmcc3_people",
+      "ksmcc3_encointer",
+    ],
+  },
+  {
+    text: "Paseo and parachains",
+    items: ["paseo", "paseo_asset_hub"],
+  },
+  {
+    text: "Westend and parachains",
+    items: [
+      "westend2",
+      "westend2_asset_hub",
+      "westend2_bridge_hub",
+      "westend2_collectives",
+      "westend2_people",
+    ],
+  },
+]

chain_docs/pregen.ts

@@ -0,0 +1,23 @@
+import fs from "fs"
+import path from "path"
+
+import { networks } from "./networks"
+
+/**
+ * The purpose of this is to get around client-side router:
+ * https://github.com/wevm/vocs/issues/210
+ * we're creating a vocs page for each network that's just reloading the page
+ */
+
+const FAKE_CHAINS_DOCS_DIR = path.join(process.cwd(), "docs", "pages", "chains")
+
+fs.mkdirSync(FAKE_CHAINS_DOCS_DIR, { recursive: true })
+for (const network of Object.keys(networks)) {
+  fs.writeFileSync(
+    path.join(FAKE_CHAINS_DOCS_DIR, `${network}.mdx`),
+    `import Reload from "../../components/Reload"
+
+<Reload />
+`,
+  )
+}

docs/components/Reload.tsx

@@ -0,0 +1,26 @@
+import React from "react"
+
+/**
+ * Related to pregen.ts
+ * @see https://github.com/wevm/vocs/issues/210
+ */
+
+const Reload: React.FC = () => {
+  if (globalThis.window) {
+    globalThis.window.location.reload()
+  }
+
+  return (
+    <>
+      <p className="vocs_Paragraph">You will see chain docs in a moment</p>
+      <aside className="vocs_Aside vocs_Callout vocs_Callout_warning">
+        <p className="vocs_Paragraph">
+          if you experience infinite reloads, then you probably need to run
+          <code className="vocs_Code">pnpm build:chain-docs</code>
+        </p>
+      </aside>
+    </>
+  )
+}
+
+export default Reload

docs/pages/chain_docs.md

@@ -0,0 +1,16 @@
+# Chain-specific docs
+
+Aside from generic documentation for polkadot-api, we also provide generated documentation for well-known chains, based
+on the metadata.  
+With these, you can search for apis like `limited_teleport_assets`, their type parameters, and the docs that
+metadata provide for them.
+
+You can also generate the same documentation for any chain, using `papi-generate-docs` binary, provided by
+`@polkadot-api/docgen` package:
+
+```
+npm install polkadot-api @polkadot-api/docgen
+papi add <...>
+papi-generate-docs --config <path-to-papi-config> --output <docs_directory>
+```
+

package.json

@@ -3,21 +3,30 @@
   "version": "0.0.0",
   "type": "module",
   "scripts": {
-    "dev": "vocs dev",
-    "build": "vocs build",
+    "dev": "NODE_ENV=development concurrently \"pnpm dev:vocs\" \"pnpm dev:chain-docs\"",
+    "dev:vocs": "NODE_ENV=development bun chain_docs/pregen.ts && vocs dev",
+    "dev:chain-docs": "NODE_ENV=development pnpm build:chain-docs && http-server -p 5174 chain_docs/dist",
+    "build": "NODE_ENV=production pnpm build:vocs && pnpm build:chain-docs",
+    "build:vocs": "bun chain_docs/pregen.ts && vocs build",
+    "build:chain-docs": "bun chain_docs/generate.ts",
     "preview": "vocs preview",
     "format": "prettier --write README.md \"docs/**/*.{js,jsx,ts,tsx,json,md}\""
   },
   "dependencies": {
+    "@polkadot-api/docgen": "^0.0.2",
     "@radix-ui/react-tabs": "^1.1.0",
     "@types/react": "^18.3.5",
+    "bun": "^1.1.28",
+    "polkadot-api": "^1.3.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "typescript": "^5.5.4",
     "vocs": "1.0.0-alpha.58"
   },
   "devDependencies": {
     "@homer0/prettier-plugin-jsdoc": "^9.0.2",
+    "concurrently": "^9.0.1",
+    "http-server": "^14.1.1",
     "prettier": "^3.3.3"
   },
   "prettier": {