add docs site

.github/workflows/ci.yml

@@ -1,10 +1,14 @@
-name: CI
+name: Test Java CI
 
 on:
   push:
     branches: [ "main" ]
+    paths:
+      - '!packages/**'
   pull_request:
     branches: [ "main" ]
+    paths:
+      - '!packages/**'
 
 # cancel previous tests if new commit is pushed to PR branch
 concurrency:

.github/workflows/docs-test.yml

@@ -0,0 +1,32 @@
+name: Test Docs deployment
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - packages/docs/**
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+defaults:
+  run:
+    working-directory: ./packages/docs
+
+jobs:
+  test-docs:
+    name: Test docs build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+      - name: Test build website
+        run: npm run build

.github/workflows/docs.yml

@@ -0,0 +1,65 @@
+name: Deploy Docs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - packages/docs/**
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+defaults:
+  run:
+    working-directory: ./packages/docs
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup NodeJS 18
+        uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: npm
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './build'
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+
+    # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+    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 }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

packages/docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

packages/docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

packages/docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

packages/docs/code_theme.ts

@@ -0,0 +1,109 @@
+export default {
+  plain: {
+    color: "#9cdcfe",
+    backgroundColor: "#1e1e1e",
+  },
+  styles: [
+    {
+      types: ["prolog"],
+      style: {
+        color: "#d7a6ff",
+      },
+    },
+    {
+      types: ["comment"],
+      style: {
+        color: "rgb(106, 153, 85)",
+      },
+    },
+    {
+      types: ["builtin", "changed", "keyword", "interpolation-punctuation", "boolean"],
+      style: {
+        color: "rgb(86, 156, 214)",
+      },
+    },
+    {
+      types: ["number", "inserted"],
+      style: {
+        color: "#b5cea8",
+      },
+    },
+    {
+      types: ["constant"],
+      style: {
+        color: "#7d7df3",
+      },
+    },
+    {
+      types: ["attr-name"],
+      style: {
+        color: "#9cdcfe",
+      },
+    },
+    {
+      types: ["variable"],
+      style: {
+        color: "#80ff80",
+      },
+    },
+    {
+      types: ["deleted", "string", "attr-value", "template-punctuation"],
+      style: {
+        color: "#ce9178",
+      },
+    },
+    {
+      types: ["selector"],
+      style: {
+        color: "rgb(215, 186, 125)",
+      },
+    },
+    {
+      // Fix tag color
+      types: ["tag"],
+      style: {
+        color: "rgb(78, 201, 176)",
+      },
+    },
+    {
+      // Fix tag color for HTML
+      types: ["tag"],
+      languages: ["markup"],
+      style: {
+        color: "rgb(86, 156, 214)",
+      },
+    },
+    {
+      types: ["punctuation", "operator"],
+      style: {
+        color: "rgb(212, 212, 212)",
+      },
+    },
+    {
+      // Fix punctuation color for HTML
+      types: ["punctuation"],
+      languages: ["markup"],
+      style: {
+        color: "#808080",
+      },
+    },
+    {
+      types: ["function"],
+      style: {
+        color: "#ffff80",
+      },
+    },
+    {
+      types: ["class-name"],
+      style: {
+        color: "rgb(78, 201, 176)",
+      },
+    },
+    {
+      types: ["char"],
+      style: {
+        color: "rgb(209, 105, 105)",
+      },
+    },
+  ],
+};

packages/docs/docs/comparison-logic.md

@@ -0,0 +1,22 @@
+---
+sidebar_position: 4
+---
+# Comparison logic
+
+Some functions use comparison for evaluation (e.g. [`$$sort`](functions/sort) & [`$$is`](functions/is)).
+
+The following table will explain what is the expected result for each comparison of 2 values:
+
+| Type                              | a ? b                                                       | Comment                              |
+|-----------------------------------|-------------------------------------------------------------|--------------------------------------|
+| **Number**                        | `a == b ? 0 : (a > b ? 1 : -1)`                             |                                      |
+| **String**                        | `a == b ? 0 : a.compareTo(b)`                               | lexicographic comparison             |
+| **Boolean**                       | `a == b ? 0 : (a ? 1 : -1)`                                 | `true` > `false`                     |
+| **Object**                        | `#keys(a) == #keys(b) ? 0 : (#keys(a) > #keys(b) ? 1 : -1)` | Compares number of keys in object    |
+| **Array**                         | `a.length == b.length ? 0 : (a.length > b.length ? 1 : -1)` | Compares number of elements in array |
+| **Null** / Types are not the same | **Not comparable** *                                        |                                      |
+
+
+:::note
+**Not comparable** values behave different in context, `$$sort` will treat both values as equal, while `$$is` will return `false` for any 2 values.
+:::

packages/docs/docs/default-locale.md

@@ -0,0 +1,7 @@
+---
+sidebar_position: 6
+---
+
+# Default Locale
+
+The default Locale used by the transformer functions is `en-US` (`Locale.US` in Java)