Merge pull request #3029 from finos/refactor-docs

Refactor docs

Author: texodus

.gitignore

@@ -60,3 +60,7 @@ vcpkg
 venv/
 rust/perspective-python/perspective_python-*.data
 .pytest-cache/
+docs/static/python
+docs/static/node
+docs/static/browser
+docs/static/viewer

Cargo.lock

@@ -23,8 +23,6 @@ default-members = [
 members = [
     "rust/lint",
     "rust/generate-metadata",
-    "rust/bootstrap",
-    "rust/bootstrap-runtime",
     "rust/bundle",
     "rust/perspective",
     "rust/perspective-client",

Cargo.toml

@@ -10,23 +10,20 @@
 // ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-const { execSync } = require("child_process");
-const os = require("os");
-const path = require("path");
+import { execSync } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+import * as url from "node:url";
+
+const __dirname = url.fileURLToPath(new URL(".", import.meta.url)).slice(0, -1);
 
 const stdio = "inherit";
-const rust_env = process.env.PSP_DEBUG ? "" : "--release";
 const env = process.env.PSP_DEBUG ? "debug" : "release";
 const cwd = path.join(process.cwd(), "dist", env);
 
-delete process.env.NODE;
+const { compress } = await import("pro_self_extracting_wasm");
 
-function bootstrap(file) {
-    execSync(`cargo run -p perspective-bootstrap -- ${rust_env} ${file}`, {
-        cwd: path.join(process.cwd(), "..", "..", "rust", "perspective-js"),
-        stdio,
-    });
-}
+delete process.env.NODE;
 
 let cmake_flags = "";
 let make_flags = "";
@@ -50,8 +47,7 @@ try {
     );
 
     execSync(
-        `emmake make -j${
-            process.env.PSP_NUM_CPUS || os.cpus().length
+        `emmake make -j${process.env.PSP_NUM_CPUS || os.cpus().length
         } ${make_flags}`,
         {
             cwd,
@@ -62,7 +58,10 @@ try {
     execSync(`cpy web/**/* ../web`, { cwd, stdio });
     execSync(`cpy node/**/* ../node`, { cwd, stdio });
     if (!process.env.PSP_HEAP_INSTRUMENTS) {
-        bootstrap(`../../cpp/perspective/dist/web/perspective-server.wasm`);
+        compress(
+            `../../cpp/perspective/dist/web/perspective-server.wasm`,
+            `../../cpp/perspective/dist/web/perspective-server.wasm`
+        );
     }
 } catch (e) {
     console.error(e);

cpp/perspective/build.js renamed to cpp/perspective/build.mjs

@@ -10,7 +10,10 @@
         "dist/cjs/**/*"
     ],
     "scripts": {
-        "build": "node ../../tools/perspective-scripts/run_emsdk.mjs node ./build.js",
+        "build": "node ../../tools/perspective-scripts/run_emsdk.mjs node ./build.mjs",
         "clean": "rimraf dist"
+    },
+    "devDependencies": {
+        "pro_self_extracting_wasm": "0.0.9"
     }
-}
+}

cpp/perspective/package.json

@@ -39,6 +39,10 @@ const examples = fs.readdirSync("static/blocks").map((ex) => {
     };
 });
 
+function link(title, path) {
+    return `<a class="dropdown__link" href="${path}">    ${title}</a>`;
+}
+
 /** @type {import('@docusaurus/types').Config} */
 const config = {
     title: "Perspective",
@@ -119,20 +123,73 @@ const config = {
                         label: "Docs",
                         items: [
                             {
-                                href: "/guide/",
-                                label: "User Guide",
+                                type: "html",
+                                value: `<a class="dropdown__link" style="font-size:16px;padding:0.25rem 0rem" href="/guide/">User Guide</a>`,
+                            },
+                            {
+                                type: "html",
+                                value: '<span style="user-select:none">Python API</span>',
+                            },
+                            {
+                                type: "html",
+                                value: `<a class="dropdown__link" href="/python/"><code>perspective</code></a>`,
+                            },
+                            {
+                                type: "html",
+                                value: `<a class="dropdown__link" href="/python/perspective/widget.html"><code>perspective.widget</code></a>`,
+                            },
+                            {
+                                type: "html",
+                                value: `<a class="dropdown__link" href="/python/perspective/handlers/aiohttp.html"><code>perspective.handlers.aiohttp</code></a>`,
+                            },
+                            {
+                                type: "html",
+                                value: `<a class="dropdown__link" href="/python/perspective/handlers/starlette.html"><code>perspective.handlers.starlette</code></a>`,
+                            },
+                            {
+                                type: "html",
+                                value: `<a class="dropdown__link" href="/python/perspective/handlers/tornado.html"><code>perspective.handlers.tornado</code></a>`,
+                            },
+                            {
+                                type: "html",
+                                value: '<span style="user-select:none">JavaScript API</span>',
+                            },
+                            {
+                                type: "html",
+                                value: link(
+                                    "<code>@finos/perspective-viewer</code>",
+                                    "/viewer/modules/perspective-viewer.html"
+                                ),
+                            },
+                            {
+                                type: "html",
+                                value: link(
+                                    "<code>@finos/perspective</code> Browser",
+                                    "/browser/modules/src_ts_perspective.browser.ts.html"
+                                ),
+                            },
+                            {
+                                type: "html",
+                                value: link(
+                                    "<code>@finos/perspective</code> Node.js",
+                                    "/node/modules/src_ts_perspective.node.ts.html"
+                                ),
+                            },
+                            {
+                                type: "html",
+                                value: '<span style="user-select:none">Rust API</span>',
                             },
                             {
                                 type: "html",
-                                value: `<a class="dropdown__link" href="https://docs.rs/perspective-js/latest/perspective_js/"><code>@finos/perspective</code> JavaScript API</a>`,
+                                value: `<a class="dropdown__link" href="https://docs.rs/perspective-js/latest/perspective_js/"><code>perspective-js</code></a>`,
                             },
                             {
                                 type: "html",
-                                value: `<a class="dropdown__link" href="https://docs.rs/perspective-python/latest/perspective_python/"><code>perspective-python</code> Python API</a>`,
+                                value: `<a class="dropdown__link" href="https://docs.rs/perspective-python/latest/perspective_python/"><code>perspective-python</code></a>`,
                             },
                             {
                                 type: "html",
-                                value: `<a class="dropdown__link" href="https://docs.rs/perspective/latest/perspective/"><code>perspective</code> Rust API</a>`,
+                                value: `<a class="dropdown__link" href="https://docs.rs/perspective/latest/perspective/"><code>perspective</code></a>`,
                             },
                         ],
                     },

docs/docusaurus.config.js

@@ -76,8 +76,8 @@ ESBuild config JSON to encode this asset as a `file`:
 ### Webpack
 
 ```javascript
-import * as SERVER_WASM from "@finos/perspective/dist/wasm/perspective-server.wasm";
-import * as CLIENT_WASM from "@finos/perspective-viewer/dist/wasm/perspective-viewer.wasm";
+import SERVER_WASM from "@finos/perspective/dist/wasm/perspective-server.wasm";
+import CLIENT_WASM from "@finos/perspective-viewer/dist/wasm/perspective-viewer.wasm";
 
 await Promise.all([
     perspective.init_server(SERVER_WASM),
@@ -90,8 +90,19 @@ Webpack config:
 ```javascript
 {
     // ...
+    module: {
+        // ...
+        rules: [
+            // ...
+            {
+                test: /\.wasm$/,
+                type: "asset/resource"
+            },
+        ]
+    },
     experiments: {
-        asyncWebAssembly: true,
+        // ...
+        asyncWebAssembly: false,
         syncWebAssembly: false,
     },
 }

docs/md/how_to/javascript/importing.md

@@ -21,7 +21,8 @@ module.exports = function (context, options) {
             }
 
             config.experiments = config.experiments || {
-                asyncWebAssembly: true,
+                asyncWebAssembly: false,
+                syncWebAssembly: false
             };
 
             config.experiments.topLevelAwait = true;
@@ -36,17 +37,22 @@ module.exports = function (context, options) {
                 type: "asset/resource",
             });
 
+            config.module.rules.push({
+                test: /\.wasm$/,
+                type: "asset/resource"
+            });
+
             return {
                 node: {
                     __filename: false,
                 },
                 plugins: isServer
                     ? [
-                          new webpack.NormalModuleReplacementPlugin(
-                              /@finos\/perspective/,
-                              "@finos/perspective/dist/esm/perspective.js"
-                          ),
-                      ]
+                        new webpack.NormalModuleReplacementPlugin(
+                            /@finos\/perspective/,
+                            "@finos/perspective/dist/esm/perspective.js"
+                        ),
+                    ]
                     : [],
             };
         },

docs/plugins/perspective-loader/index.js

@@ -19,8 +19,8 @@ const WORKER = (async () => {
     );
 
     await Promise.all([
-        perspective.init_server(wasm),
-        perspective_viewer.init_client(client_wasm),
+        perspective.init_server(wasm.then(x => x.default)),
+        perspective_viewer.init_client(client_wasm.then(x => x.default)),
     ]);
 
     return await perspective.worker();

docs/src/data/worker.js

@@ -20,6 +20,6 @@
         "superstore-arrow": "3.0.0"
     },
     "devDependencies": {
-        "esbuild": "^0.14.54"
+        "esbuild": "^0.25.5"
     }
 }