docs: add document (#12)

* chore: init docs * chore: stat * chore: switch github highlight * chore: stat * feat: add reload * feat: docs anchor * feat: done
nonzzz · Feb 5, 2025 · 831959f · 831959f
1 parent c709aeb
commit 831959f
Show file tree

Hide file tree

Showing 16 changed files with 1,110 additions and 20 deletions.
diff --git a/.github/workflows/deploy-site.yaml b/.github/workflows/deploy-site.yaml
@@ -15,7 +15,7 @@ jobs:
         with:
           node-version: 22.9.0
       - name: Build site
-        run: make build-server
+        run: make build-docs
 
       - name: Deploy site
         uses: JamesIves/[email protected]

diff --git a/Makefile b/Makefile
@@ -31,10 +31,12 @@ dev-server:
 	@echo "Start dev server"
 	./node_modules/.bin/esbuild $(FLAGS) --define:LIVE_RELOAD=true --watch --servedir=./display
 
-build-server:
-	@echo "Build server"
-	./node_modules/.bin/esbuild $(FLAGS) --define:LIVE_RELOAD=false
-
 lint:
 	@echo "Lint"
 	./node_modules/.bin/eslint --fix .
+
+dev-docs:
+	./node_modules/.bin/tsx scripts/serve.ts
+
+build-docs:
+	./node_modules/.bin/tsx scripts/render.ts
diff --git a/dev/index.html b/dev/index.html
@@ -3,7 +3,7 @@
   <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Document</title>
+    <title>Squarified Example</title>
     <style>
     #app, html, body {
       margin: 0;

diff --git a/docs/api.yaml b/docs/api.yaml
@@ -0,0 +1,66 @@
+title: Api
+body:
+  - h1: Api
+  - p: All the methods and options of the squarified library are documented here.
+
+  - h2: Draw Layout Api
+
+  - p: |
+      The draw layout API is the main API for the treemap. It provides methods to draw the treemap layout.
+      Now, the draw layout is opinionated and provides a minimalistic API to draw the treemap layout.
+
+  - h3: createTreemap
+
+  - p: >
+      Create a new instance of the treemap. This method returns a new instance of the treemap.
+
+  - pre.js: |
+      import { createTreemap } from 'squarified'
+      const treemap = createTreemap()
+
+  - h2: Data Transform Api
+
+  - p: |
+      The data transform API provides methods to transform the data into a format that the treemap can understand.
+
+  - h3: c2m
+
+  - p: >
+      Convert the original data into a format data that the treemap can understand. This method returns a new data format.
+
+  - pre.js: |
+      import { c2m } from 'squarified'
+      const data = [{ name: 'root', value: 100 }, { name: 'root2', value: 50}, { name: 'root3', value: 150 }]
+      const transformedData = c2m(data, 'value' , (d) => ({ ...d, label: d.name }))
+
+  - h3: findRelativeNode
+
+  - p: >
+      Find the relative node of the given node. This method returns the relative node of the given node.
+      Note: This function is based on the `visit` and respect the calculated coordinates.
+
+  - h3: findRelativeNodeById
+
+  - p: >
+      Find the relative node of the given node by id. This method returns the relative node of the given node by id.
+      Note: This function is based on the `visit`.
+
+  - h3: flattenModule
+
+  - p: >
+      Flatten the module. This method returns the flattened module.
+
+  - h3: getNodeDepth
+
+  - p: >
+      Get the depth of the node. This method returns the depth of the node.
+
+  - h3: sortChildrenByKey
+
+  - p: >
+      Sort the children by key. This method returns the sorted children by key.
+
+  - h3: visit
+
+  - p: >
+      Walk Nodes.
diff --git a/docs/faq.yaml b/docs/faq.yaml
@@ -0,0 +1,19 @@
+index:
+  title: A minimal and powerful treemap component.
+  body:
+    - h1: Squarified
+    - p: A treemap layout algorithm that optimizes for aspect ratio.
+
+    - p: "Major features:"
+    - ul:
+        - "Minimalistic API"
+        - "Powerful layout algorithm"
+        - "Highly customizable"
+        - "Supports zooming and panning"
+
+    - p: >
+        Check out the [getting started](/getting-started) guide to learn how to use.
+
+getting-started: "getting-started.yaml"
+api: "api.yaml"
+faq: "faq.yaml"
diff --git a/docs/getting-started.yaml b/docs/getting-started.yaml
@@ -0,0 +1,55 @@
+title: Getting Started
+body:
+  - h1: Getting Started
+
+  - h2: Install squarified
+
+  - p: >
+      First, download and install this package from [npm](https://docs.npmjs.com/cli/v8/commands/npm-install)
+
+  - pre.shell: >
+      $ npm install squarified
+
+  - h2: The first application
+
+  - p: >
+      This is a simple example of how to use it. Create a new file named `index.html` and `pre.js` in the same directory.
+      copy and paste the following code into the files respectively and then run the `index.html` by a static server. (such as `npx http-server`)
+
+  - pre.html: |
+      <!DOCTYPE html>
+      <html lang="en">
+        <head>
+          <meta charset="UTF-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1.0">
+          <title>Squarified</title>
+          <style>
+            #app, html, body {
+              width: 100%;
+              height: 100vh;
+            }
+          </style>
+        </head>
+        <body>
+          <div id="app"></div>
+          <script src="pre.js"></script>
+        </body>
+      </html>
+  - pre.js: |
+      // pre.js
+      import { createTreemap, presetDecorator } from 'squarified'
+      const data = [{
+        name: 'root',
+        weight: 100,
+        groups: [
+          { name: 'a', weight: 10 },
+          { name: 'b', weight: 20 },
+          { name: 'c', weight: 30 },
+          { name: 'd', weight: 40 },
+        ]
+      }]
+      const treemap = createTreemap()
+      treemap.use('decorator', presetDecorator())
+      const el = document.getElementById('app')
+      treemap.init(el)
+      treemap.setOptions({ data })
diff --git a/docs/index.yaml b/docs/index.yaml
@@ -0,0 +1,18 @@
+index:
+  title: A minimal and powerful treemap component.
+  body:
+    - h1: Squarified
+    - p: A treemap layout algorithm that optimizes for aspect ratio.
+
+    - p: "Major features:"
+    - ul:
+        - "Minimalistic API"
+        - "Powerful layout algorithm(Based on <a href='https://vanwijk.win.tue.nl/stm.pdf'>Squarified Treemaps</a>)"
+        - "Highly customizable"
+        - "Supports zooming and panning"
+
+    - p: >
+        Check out the [getting started](/getting-started) guide to learn how to use.
+
+getting-started: "getting-started.yaml"
+api: "api.yaml"
diff --git a/global.d.ts b/global.d.ts
@@ -1,2 +1,4 @@
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type Any = any
+
+type AnyObject = Record<keyof Any, Any>
diff --git a/package.json b/package.json
@@ -22,14 +22,22 @@
   "author": "Kanno",
   "license": "MIT",
   "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/markdown-it": "^14.1.2",
     "@types/node": "^22.7.4",
+    "chokidar": "^4.0.3",
     "dprint": "^0.47.2",
     "esbuild": "^0.24.0",
     "eslint": "^9.16.0",
     "eslint-config-kagura": "^3.0.1",
+    "highlight.js": "^11.11.1",
     "jiek": "^2.3.3",
+    "js-yaml": "^4.1.0",
+    "markdown-it": "^14.1.0",
+    "tinyexec": "^0.3.2",
+    "tsx": "^4.19.2",
     "typescript": "^5.7.3",
-    "vite-bundle-analyzer": "^0.16.0"
+    "vite-bundle-analyzer": "^0.16.2"
   },
   "pnpm": {
     "overrides": {