Merge branch 'main' into jelly-docs

Author: badmonster0

.github/workflows/docs.yml

@@ -37,8 +37,21 @@ jobs:
       - name: Test build website
         run: yarn build
 
+  deploy-precheck:
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name != 'pull_request' }}
+    outputs:
+      gh-deploy-key: ${{ steps.gh-deploy-key.outputs.defined }}
+    steps:
+        - id: gh-deploy-key
+          env:
+              GH_PAGES_DEPLOY: ${{ secrets.GH_PAGES_DEPLOY }}
+          if: "${{ env.GH_PAGES_DEPLOY != '' }}"
+          run: echo "defined=true" >> $GITHUB_OUTPUT
+
   deploy:
-    if: github.event_name != 'pull_request'
+    needs: [deploy-precheck]
+    if: ${{ needs.deploy-precheck.outputs.gh-deploy-key == 'true' }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -61,6 +74,8 @@ jobs:
         env:
           USE_SSH: true
         run: |
+          export COCOINDEX_DOCS_POSTHOG_API_KEY=${{ secrets.COCOINDEX_DOCS_POSTHOG_API_KEY }}
+          export COCOINDEX_DOCS_MIXPANEL_API_KEY=${{ secrets.COCOINDEX_DOCS_MIXPANEL_API_KEY }}
           git config --global user.email "[email protected]"
           git config --global user.name "CocoIndex"
           yarn install --frozen-lockfile

docs/docs/core/basics.md

@@ -22,9 +22,8 @@ An indexing flow involves source data and transformed data (either as an interme
 Each piece of data has a **data type**, falling into one of the following categories:
 
 *   Basic type.
-*   Composite type
-    *   Struct: a collection of **fields**, each with a name and a type.
-    *   Table: a collection of **rows**, each of which is a struct with specified schema.
+*   Struct type: a collection of **fields**, each with a name and a type.
+*   Collection type: a collection of **rows**, each of which is a struct with specified schema. A collection type can be a table (which has a key field) or a list (ordered but without key field).
 
 An indexing flow always has a top-level struct, containing all data within and managed by the flow.
 

docs/docs/core/data_types.mdx

@@ -17,37 +17,50 @@ This is the list of all basic types supported by CocoIndex:
 
 | Type | Type in Python | Original Type in Python |
 |------|-----------------|--------------------------|
-| `bytes` | `bytes` | `bytes` |
-| `str` | `str` | `str` |
-| `bool` | `bool` | `bool` |
-| `int64` | `int` | `int` |
-| `float32` | `cocoindex.typing.Float32` |`float` | 
-| `float64` |  `cocoindex.typing.Float64` |`float` |
-| `range` | `cocoindex.typing.Range`  | `tuple[int, int]` |
-| `vector(*type* [, *N*])` |`Annotated[list[type], cocoindex.typing.Vector(dim=N)]` | `list[type]` | 
-| `json` | `cocoindex.typing.Json` | Any type convertible to JSON by `json` package | 
+| bytes | `bytes` | `bytes` |
+| str | `str` | `str` |
+| bool | `bool` | `bool` |
+| int64 | `int` | `int` |
+| float32 | `cocoindex.typing.Float32` |`float` | 
+| float64 |  `cocoindex.typing.Float64` |`float` |
+| range | `cocoindex.typing.Range`  | `tuple[int, int]` |
+| vector[*type*, *N*?] |`Annotated[list[type], cocoindex.typing.Vector(dim=N)]` | `list[type]` | 
+| json | `cocoindex.typing.Json` | Any type convertible to JSON by `json` package | 
 
 For some types, CocoIndex Python SDK provides annotated types with finer granularity than Python's original type, e.g. `Float32` and `Float64` for `float`, and `vector` has dimension information.
 
 When defining [custom functions](/docs/core/custom_function), use the specific types as type annotations for arguments and return values.
 So CocoIndex will have information about the specific type.
 
-### Struct
+### Struct Type
 
 A struct has a bunch of fields, each with a name and a type.
 
-### Table
+In Python, a struct type is represented by a [dataclass](https://docs.python.org/3/library/dataclasses.html),
+and all fields must be annotated with a specific type. For example:
 
-A table has a collection of rows, each of which is a struct with specified schema.
+```python
+from dataclasses import dataclass
 
-The first field of a table is always the primary key.
+@dataclass
+class Order:
+    order_id: str
+    name: str
+    price: float
+```
 
-:::note
+### Collection Types
 
-CocoIndex will support functions taking struct and table types as arguments or returning composite types soon.
-We'll update this section with corresponding Python types by then.
+A collection type models a collection of rows, each of which is a struct with specific schema.
 
-:::
+We have two specific types of collection:
+
+| Type | Description |Type in Python | Original Type in Python |
+|------|-------------|---------------|-------------------------|
+| Table[*type*] | The first field is the key, and CocoIndex enforces its uniqueness | `cocoindex.typing.Table[type]` | `list[type]` |
+| List[*type*] | No key field; row order is preserved | `cocoindex.typing.List[type]` | `list[type]` |
+
+For example, we can use `cocoindex.typing.Table[Order]` to represent a table of orders, and the first field `order_id` will be taken as the key field.
 
 ## Types to Create Indexes
 

docs/docusaurus.config.ts

@@ -1,3 +1,4 @@
+import webpack from 'webpack';
 import { themes as prismThemes } from 'prism-react-renderer';
 import type { Config } from '@docusaurus/types';
 import type * as Preset from '@docusaurus/preset-classic';
@@ -33,14 +34,17 @@ const config: Config = {
   },
 
   plugins: [
-    [
-      "posthog-docusaurus",
-      {
-        apiKey: "phc_SgKiQafwZjHu4jQW2q402gbz6FYQ2NJRkcgooZMNNcy",
-        appUrl: "https://us.i.posthog.com",
-        enableInDevelopment: false,
-      },
-    ],
+    () => ({
+      name: 'load-env-vars',
+      configureWebpack: () => ({
+        mergeStrategy: { plugins: "append", resolve: "merge" },
+        plugins: [
+          new webpack.DefinePlugin({
+            'process.env.COCOINDEX_DOCS_MIXPANEL_API_KEY': JSON.stringify(process.env.COCOINDEX_DOCS_MIXPANEL_API_KEY),
+          })
+        ],
+      }),
+    }),
   ],
 
   presets: [
@@ -147,4 +151,16 @@ const config: Config = {
   } satisfies Preset.ThemeConfig,
 };
 
+
+if (!!process.env.COCOINDEX_DOCS_POSTHOG_API_KEY) {
+  config.plugins.push([
+    "posthog-docusaurus",
+    {
+      apiKey: process.env.COCOINDEX_DOCS_POSTHOG_API_KEY,
+      appUrl: "https://us.i.posthog.com",
+      enableInDevelopment: false,
+    },
+  ]);
+}
+
 export default config;

docs/src/theme/Root.js

@@ -2,11 +2,12 @@ import React from 'react';
 import mixpanel from 'mixpanel-browser';
 
 // Default implementation, that you can customize
-export default function Root({children}) {
+export default function Root({ children }) {
   React.useEffect(() => {
-    if (typeof window !== 'undefined') {
+    const mixpanelApiKey = process.env.COCOINDEX_DOCS_MIXPANEL_API_KEY;
+    if (typeof window !== 'undefined' && !!mixpanelApiKey) {
       // Initialize Mixpanel with the token
-      mixpanel.init('46addeb6bedf8684a445aced6e67c76e', {
+      mixpanel.init(mixpanelApiKey, {
         track_pageview: true,
         debug: process.env.NODE_ENV === 'development'
       });