Add Python documentation (#123)

Author: linhr

README.md

@@ -11,6 +11,8 @@ You need Node.js to build the documentation.
 
 On macOS, you can install rustup and the Node.js runtime via Homebrew.
 
+<!-- TODO: make it clear that the following is an alternative way to install rustup -->
+
 ```bash
 brew install rustup
 brew install node
@@ -33,6 +35,8 @@ You also need the following tools when working on the project.
 
 On macOS, you can install these tools via Homebrew.
 
+<!-- TODO: investigate if we can install Maturin locally -->
+
 ```bash
 brew install protobuf hatch maturin zig pnpm
 ```

docs/.vitepress/config.mts

@@ -36,7 +36,6 @@ function analyticsHead(): HeadConfig[] {
 export default async () => {
   return defineConfig({
     base: siteBase(),
-    lastUpdated: true,
     lang: "en-US",
     title: headTitle,
     description: headDescription,
@@ -52,7 +51,10 @@ export default async () => {
       ["meta", { property: "og:image", content: headImage }],
       ["meta", { property: "og:type", content: "website" }],
       ["meta", { property: "og:site_name", content: "Sail documentation" }],
-      ['link', { rel: 'icon', type: 'image/png', href: `${siteBase()}favicon.png` }],
+      [
+        "link",
+        { rel: "icon", type: "image/png", href: `${siteBase()}favicon.png` },
+      ],
       ...analyticsHead(),
     ],
     transformPageData(pageData) {
@@ -69,20 +71,34 @@ export default async () => {
         "meta",
         { property: "og:url", content: canonicalUrl },
       ]);
+
+      if (pageData.params?.sphinx) {
+        pageData.frontmatter.prev = pageData.params.prev || {
+          link: "/reference/",
+          text: "Reference",
+        };
+        pageData.frontmatter.next = pageData.params.next ?? false;
+      }
     },
     // Exclude directories starting with an underscore. Such directories are
     // internal (e.g. containing pages to be included in other pages).
     srcExclude: ["**/_*/**/*.md"],
     ignoreDeadLinks: [/^https?:\/\/localhost(:\d+)?(\/.*)?$/],
     themeConfig: {
-      nav: [{ text: "Home", link: "/" }],
+      logo: "/favicon.png",
+      nav: [
+        { text: "User Guide", link: "/guide/" },
+        { text: "Development", link: "/development/" },
+        { text: "Reference", link: "/reference/" },
+      ],
       notFound: {
         quote: "The page does not exist.",
       },
       sidebar: {
         "/": [
           {
             text: "User Guide",
+            link: "/guide/",
             items: [
               {
                 text: "Installation",
@@ -93,6 +109,17 @@ export default async () => {
           {
             text: "Development",
             link: "/development/",
+            items: [],
+          },
+          {
+            text: "Reference",
+            link: "/reference/",
+            items: [
+              {
+                text: "Python API Reference",
+                link: "/reference/python/",
+              },
+            ],
           },
         ],
       },

docs/development/index.md

@@ -0,0 +1 @@
+# Development

docs/guide/index.md

@@ -0,0 +1 @@
+# User Guide

docs/guide/installation.md

@@ -0,0 +1 @@
+# Installation

docs/index.md

@@ -8,3 +8,4 @@ Welcome to the Sail documentation!
 
 - [User Guide](/guide/)
 - [Development](/development/)
+- [Reference](/reference/)

docs/reference/index.md

@@ -0,0 +1,3 @@
+# Reference
+
+- [Python API Reference](/reference/python/)

docs/reference/python/[page].md

@@ -0,0 +1 @@
+<!-- @content -->

docs/reference/python/[page].paths.ts

@@ -0,0 +1,51 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const SPHINX_BUILD_OUTPUT = path.join(
+  __dirname,
+  "../../../python/pysail/docs/_build",
+);
+
+export default {
+  async paths() {
+    const entries = await fs.promises.readdir(SPHINX_BUILD_OUTPUT, {
+      withFileTypes: true,
+      recursive: true,
+    });
+    const files = entries.filter(
+      (entry) => entry.isFile() && entry.name.endsWith(".fjson"),
+    );
+
+    const paths = await Promise.all(
+      files.map(async (entry) => {
+        if (entry.name === "search.fjson" || entry.name === "genindex.fjson") {
+          return null;
+        }
+        const file = path.join(entry.parentPath, entry.name);
+        const content = await fs.promises.readFile(file, "utf-8");
+        const data = JSON.parse(content);
+        const page = path
+          .relative(SPHINX_BUILD_OUTPUT, file)
+          .replace(/^index\.fjson$/, "/index")
+          .replace(/[/\\]index\.fjson$/, "/index")
+          // We must turn non-index pages into directories, since Sphinx handles URL in this way
+          // in `JSONHTMLBuilder`, which may generate relative URLs containing `../` may appear in the HTML.
+          .replace(/\.fjson$/, "/index");
+        return {
+          params: {
+            sphinx: true,
+            page,
+            prev: data.prev
+              ? { link: data.prev.link, text: data.prev.title }
+              : false,
+            next: data.next
+              ? { link: data.next.link, text: data.next.title }
+              : false,
+          },
+          content: data.body,
+        };
+      }),
+    );
+    return paths.filter((path) => path !== null);
+  },
+};

package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "private": true,
   "scripts": {
-    "lint": "eslint docs",
+    "lint": "vue-tsc --noEmit && eslint docs",
     "format": "prettier --write \"*.{js,json,md}\" \".github/**/*.{yml,yaml}\" \"docs/**/*.{ts,mts,vue,css,md}\"",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
@@ -13,8 +13,8 @@
     "@ianvs/prettier-plugin-sort-imports": "^4.3.1",
     "@types/eslint__js": "^8.42.3",
     "@types/node": "^20.14.14",
-    "@typescript-eslint/eslint-plugin": "^8.0.0",
-    "@typescript-eslint/parser": "^8.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.1",
+    "@typescript-eslint/parser": "^8.0.1",
     "autoprefixer": "^10.4.20",
     "eslint": "^9.8.0",
     "eslint-config-prettier": "^9.1.0",
@@ -25,9 +25,11 @@
     "prettier": "^3.3.3",
     "prettier-plugin-tailwindcss": "^0.5.14",
     "tailwindcss": "^3.4.7",
-    "typescript": "^4.9.5",
-    "typescript-eslint": "^8.0.0",
-    "vitepress": "^1.3.1"
+    "typescript": "^5.5.4",
+    "typescript-eslint": "^8.0.1",
+    "vitepress": "^1.3.2",
+    "vue": "^3.4.35",
+    "vue-tsc": "^2.0.29"
   },
   "postcss": {
     "plugins": {