docs: add initial documentation site

.changeset/config.json

@@ -1,10 +1,10 @@
 {
-	"$schema": "https://unpkg.com/@changesets/config@2.3.0/schema.json",
-	"changelog": [
-		"@svitejs/changesets-changelog-github-compact",
-		{ "repo": "manzt/zarrita.js" }
-	],
-	"commit": false,
-	"access": "public",
-	"baseBranch": "main"
+  "$schema": "https://unpkg.com/@changesets/config@2.3.0/schema.json",
+  "changelog": [
+    "@svitejs/changesets-changelog-github-compact",
+    { "repo": "manzt/zarrita.js" }
+  ],
+  "commit": false,
+  "access": "public",
+  "baseBranch": "main"
 }

.github/workflows/pages.yml

@@ -0,0 +1,45 @@
+name: Pages
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+
+  Build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: pnpm/action-setup@v2
+        with:
+          version: 8
+      - run: |
+          pnpm install
+          cd docs
+          pnpm build
+    - name: Upload Pages artifact
+      uses: actions/upload-pages-artifact@v2
+      with:
+        path: .vitepress/dist
+
+  Deploy:
+    needs: Build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    # Specify runner + deployment step
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2 # or the latest "vX.X.X" version tag for this action

.gitignore

@@ -1,7 +1,7 @@
 node_modules/
 *.zr3/
 dist/
-docs/
 *.tgz
 
 .venv
+docs/.vitepress/cache

README.md

@@ -2,100 +2,37 @@
 
 # zarrita.js
 
-**zarrita** is a minimal and modular implementation of Zarr in TypeScript.
+**zarrita** is a minimal & modular Zarr implementation in TypeScript.
 
 - Zero dependencies (optionally
   [`scijs/ndarray`](https://github.com/scijs/ndarray))
-- Supports **v2** or **v3** protocols
 - Runs natively in **Node**, **Browsers**, and **Deno** (ESM)
-- Supports **C-order** & **F-order** arrays
-- Handles **little endian** or **big endian** data-types
-- Handles **number**, **bigint**, **string**, and **boolean** data-types
-- Configurable codes via
-  [`numcodecs`](https://github.com/manzt/numcodecs.js)
-- Allows _very_ flexible storage
-- Provides rich, in-editor **type information** via
-  [template literal types](https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html)
-
-## Zarr building blocks
-
-**zarrita's** API is almost entirely
-[_tree-shakeable_](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking),
-meaning users are able to pick and choose only the features of Zarr which are
-necessary for an applications. At its core, the `zarr.Array` `class` allows
-reading individual _chunks_. "Fancy-indexing" and "slicing" are accomplished via
-(optional) _functions_ which operate on `zarr.Array` objects, and thus you only
-"pay" for these features if used (when bundling for the web).
-
-This design choice differs from existing implemenations of Zarr in JavaScript,
-and allows **zarrita** to be both minimal _and_ more feature-complete if
-necessary.
-
-## Example:
+- Supports **v2** or **v3** protocols, C & F-order arrays, and diverse data-types
+- Allows flexible storage backends and compression codecs
+- Provides rich, in-editor type information via [template literal types](https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html)
+
+## Usage
 
 ```javascript
 import * as zarr from "@zarrita/core";
 import { FetchStore } from "@zarrita/storage";
 
-// intialize store
 const store = new FetchStore("http://localhost:8080/data.zarr");
-
-// open array from root (note that dtype is unknown)
 const arr = await zarr.open.v2(store, { kind: "array" }); // zarr.Array<DataType, FetchStore>
 
-arr; // zarr.Array<DataType, FetchStore>
-arr.shape; // [5, 10]
-arr.chunk_shape; // [2, 5]
-arr.dtype; // "int32"
-
 // read chunk
 const chunk = await arr.get_chunk([0, 0]);
-console.log(chunk);
-// {
-//   data: Int32Array(10) [
-//      0,  1,  2,  3,  4,
-//     10, 11, 12, 13, 14,
-//   ],
-//   shape: [ 2, 5 ],
-// }
-
-// read combined chunks/selections
 
 // Option 1: Builtin getter, no dependencies
 import { get, slice } from "@zarrita/indexing";
 const full = await get(arr); // { data: Int32Array, shape: number[], stride: number[] }
 
 // Option 2: scijs/ndarray getter, includes `ndarray` and `ndarray-ops` dependencies
-import { get } from "zarrita/ndarray";
+import { get } from "@zarrita/ndarray";
 const full = await get(arr); // ndarray.Ndarray<Int32Array>
 
-console.log(full);
-// {
-//   data: Int32Array(50) [
-//      0,  1,  2,  3,  4,  5,  6,  7,  8,  9,
-//     10, 11, 12, 13, 14, 15, 16, 17, 18, 19,
-//     20, 21, 22, 23, 24, 25, 26, 27, 28, 29,
-//     30, 31, 32, 33, 34, 35, 36, 37, 38, 39,
-//     40, 41, 42, 43, 44, 45, 46, 47, 48, 49,
-//   ],
-//   shape: [ 5, 10 ],
-//   stride: [ 10, 1 ]
-// }
-
 // read region
 const region = await get(arr, [null, zarr.slice(6)]);
-console.log(region);
-// {
-//   data: Int32Array(30) [
-//      0,  1,  2,  3,  4,  5,
-//     10, 11, 12, 13, 14, 15,
-//     20, 21, 22, 23, 24, 25,
-//     30, 31, 32, 33, 34, 35,
-//     40, 41, 42, 43, 44, 45,
-//   ],
-//   shape: [ 5, 6 ],
-//   stride: [ 6, 1 ]
-// }
 ```
 
 ## Usage

docs/.vitepress/config.mts

@@ -0,0 +1,38 @@
+import { defineConfig } from "vitepress";
+import { tabsMarkdownPlugin } from "vitepress-plugin-tabs";
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+	title: "zarrita.js",
+	description: "Zarr building blocks for JavaScript",
+	themeConfig: {
+		// https://vitepress.dev/reference/default-theme-config
+		nav: [
+			{ text: "Home", link: "/" },
+			{ text: "Guide", link: "/guide/what-is-zarrita" },
+		],
+		sidebar: {
+			"/guide/": { base: "/guide/", items: sidebarGuide() },
+		},
+		socialLinks: [
+			{ icon: "github", link: "https://github.com/manzt/zarrita.js" },
+		],
+	},
+	markdown: {
+		config(md) {
+			md.use(tabsMarkdownPlugin);
+		},
+	},
+});
+
+function sidebarGuide() {
+	return [
+		{
+			text: "Introduction",
+			items: [
+				{ text: "What is zarrita.js?", link: "what-is-zarrita" },
+				{ text: "Get Started", link: "get-started" },
+			],
+		},
+	];
+}

docs/.vitepress/theme/index.ts

@@ -0,0 +1,18 @@
+// https://vitepress.dev/guide/custom-theme
+import { h } from "vue";
+import Theme from "vitepress/theme";
+import { enhanceAppWithTabs } from "vitepress-plugin-tabs/client";
+
+import "./style.css";
+
+export default {
+	extends: Theme,
+	Layout: () => {
+		return h(Theme.Layout, null, {
+			// https://vitepress.dev/guide/extending-default-theme#layout-slots
+		});
+	},
+	enhanceApp({ app, router, siteData }) {
+		enhanceAppWithTabs(app);
+	},
+};

docs/.vitepress/theme/style.css

@@ -0,0 +1,91 @@
+/**
+ * Customize default theme styling by overriding CSS variables:
+ * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
+ */
+
+/**
+ * Colors
+ * -------------------------------------------------------------------------- */
+
+ :root {
+  --vp-c-brand: #ec4899;
+  --vp-c-brand-light: #f9a8d4;
+  --vp-c-brand-lighter: #fbcfe8;
+  --vp-c-brand-lightest: #fce7f3;
+  --vp-c-brand-dark: #be185d;
+  --vp-c-brand-darker: #831843;
+  --vp-c-brand-dimm: #500724;
+}
+
+/**
+ * Component: Button
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-button-brand-border: var(--vp-c-brand-light);
+  --vp-button-brand-text: var(--vp-c-white);
+  --vp-button-brand-bg: var(--vp-c-brand);
+  --vp-button-brand-hover-border: var(--vp-c-brand-light);
+  --vp-button-brand-hover-text: var(--vp-c-white);
+  --vp-button-brand-hover-bg: var(--vp-c-brand-light);
+  --vp-button-brand-active-border: var(--vp-c-brand-light);
+  --vp-button-brand-active-text: var(--vp-c-white);
+  --vp-button-brand-active-bg: var(--vp-button-brand-bg);
+}
+
+/**
+ * Component: Home
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: -webkit-linear-gradient(
+    120deg,
+    var(--vp-c-brand) 30%,
+    var(--vp-c-brand-lightest)
+  );
+
+  --vp-home-hero-image-background-image: linear-gradient(
+    -45deg,
+    var(--vp-c-brand) 50%,
+    var(--vp-brand-lighest) 50%
+  );
+  --vp-home-hero-image-filter: blur(40px);
+}
+
+@media (min-width: 640px) {
+  :root {
+    --vp-home-hero-image-filter: blur(56px);
+  }
+}
+
+@media (min-width: 960px) {
+  :root {
+    --vp-home-hero-image-filter: blur(72px);
+  }
+}
+
+/**
+ * Component: Custom Block
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-custom-block-tip-border: var(--vp-c-brand);
+  --vp-custom-block-tip-text: var(--vp-c-brand-darker);
+  --vp-custom-block-tip-bg: var(--vp-c-brand-dimm);
+}
+
+.dark {
+  --vp-custom-block-tip-border: var(--vp-c-brand);
+  --vp-custom-block-tip-text: var(--vp-c-brand-lightest);
+  --vp-custom-block-tip-bg: var(--vp-c-brand-dimm);
+}
+
+/**
+ * Component: Algolia
+ * -------------------------------------------------------------------------- */
+
+.DocSearch {
+  --docsearch-primary-color: var(--vp-c-brand) !important;
+}
+