switch to use vitepress (#100)

Signed-off-by: Kangrui Ye <[email protected]>
cloudflightio · May 24, 2023 · cfb1ed1 · cfb1ed1
1 parent 70f8b56
commit cfb1ed1
Show file tree

Hide file tree

Showing 20 changed files with 725 additions and 1,029 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -1,23 +1,23 @@
 name: Build
 on:
-  push:
-    branches:
-      - 'main'
-  pull_request:
+    push:
+        branches:
+            - 'main'
+    pull_request:
 jobs:
-  build:
-    name: Build
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: volta-cli/[email protected]
-      - name: Install
-        run: yarn install --immutable --immutable-cache --check-cache
-      - name: Build
-        run: yarn run build
-      - name: Test
-        run: yarn run test
-      - name: Lint
-        run: yarn run lint
-      - name: Generate docs
-        run: yarn run generate:docs
+    build:
+        name: Build
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v3
+            - uses: volta-cli/[email protected]
+            - name: Install
+              run: yarn install --immutable --immutable-cache --check-cache
+            - name: Generate docs
+              run: yarn run generate:docs
+            - name: Build
+              run: yarn run build
+            - name: Test
+              run: yarn run test
+            - name: Lint
+              run: yarn run lint
diff --git a/apps/documentation/project.json b/apps/documentation/project.json
@@ -19,8 +19,8 @@
             "outputs": ["{options.outputPath}"],
             "inputs": ["default", "^default"],
             "options": {
-                "outputPath": "dist/apps/documentation",
-                "command": "vuepress build apps/documentation/src"
+                "outputPath": "dist/apps/documentation/cloudflight-js-utils",
+                "command": "vitepress build apps/documentation/src"
             }
         },
         "serve": {

diff --git a/apps/documentation/src/.vitepress/config.ts b/apps/documentation/src/.vitepress/config.ts
@@ -0,0 +1,80 @@
+import {defineConfig, DefaultTheme} from 'vitepress';
+import akitaReadItems from '../api/akita-read/typedoc-sidebar.json';
+import angularDisplayItems from '../api/angular-display/typedoc-sidebar.json';
+import angularLoggerItems from '../api/angular-logger/typedoc-sidebar.json';
+import angularTeleportItems from '../api/angular-teleport/typedoc-sidebar.json';
+import concurrencyUtilsItems from '../api/concurrency-utils/typedoc-sidebar.json';
+import loggerItems from '../api/logger/typedoc-sidebar.json';
+import rxjsReadItems from '../api/rxjs-read/typedoc-sidebar.json';
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+    title: 'Cloudflight Js Utils',
+    description: 'Documentation page for Cloudflight Js Utils',
+    themeConfig: {
+        sidebar: {
+            '/api/akita-read/': [
+                {
+                    text: 'Akita Read',
+                    link: '/api/akita-read/',
+                    items: removeDuplicateItems(akitaReadItems as unknown as DefaultTheme.SidebarItem[]),
+                },
+            ],
+            '/api/angular-display/': [
+                {
+                    text: 'Angular Display',
+                    link: '/api/angular-display/',
+                    items: removeDuplicateItems(angularDisplayItems as unknown as DefaultTheme.SidebarItem[]),
+                },
+            ],
+            '/api/angular-logger/': [
+                {
+                    text: 'Angular Logger',
+                    link: '/api/angular-logger/',
+                    items: removeDuplicateItems(angularLoggerItems as unknown as DefaultTheme.SidebarItem[]),
+                },
+            ],
+            '/api/angular-teleport/': [
+                {
+                    text: 'Angular Teleport',
+                    link: '/api/angular-teleport/',
+                    items: removeDuplicateItems(angularTeleportItems as unknown as DefaultTheme.SidebarItem[]),
+                },
+            ],
+            '/api/concurrency-utils/': [
+                {
+                    text: 'Concurrency Utils',
+                    link: '/api/concurrency-utils/',
+                    items: removeDuplicateItems(concurrencyUtilsItems as unknown as DefaultTheme.SidebarItem[]),
+                },
+            ],
+            '/api/logger/': [
+                {
+                    text: 'Logger',
+                    link: '/api/logger/',
+                    items: removeDuplicateItems(loggerItems as unknown as DefaultTheme.SidebarItem[]),
+                },
+            ],
+            '/api/rxjs-read/': [
+                {
+                    text: 'Rxjs Read',
+                    link: '/api/rxjs-read/',
+                    items: removeDuplicateItems(rxjsReadItems as unknown as DefaultTheme.SidebarItem[]),
+                },
+            ],
+        },
+        socialLinks: [{icon: 'github', link: 'https://github.com/cloudflightio/cloudflight-js-utils'}],
+    },
+    // we need to put it in the subfolder otherwise serving with Nx does not work correctly
+    outDir: '../../../dist/apps/documentation/cloudflight-js-utils',
+});
+
+function removeDuplicateItems(items: DefaultTheme.SidebarItem[]): DefaultTheme.SidebarItem[] {
+    return items.reduce<DefaultTheme.SidebarItem[]>((acc, item) => {
+        if (acc.some((existingItem) => existingItem.link === item.link)) {
+            return acc;
+        }
+
+        return [...acc, item];
+    }, []);
+}
diff --git a/apps/documentation/src/.vuepress/config.ts b/apps/documentation/src/.vuepress/config.ts
diff --git a/apps/documentation/src/index.md b/apps/documentation/src/index.md
@@ -2,10 +2,10 @@
 
 Documentation page for Cloudflight Js Utils. Please refer to each documentation subpage for more information.
 
-- [@cloudflight/akita-read](api/akita-read)
-- [@cloudflight/angular-display](api/angular-display)
-- [@cloudflight/angular-logger](api/angular-logger)
-- [@cloudflight/angular-teleport](api/angular-teleport)
-- [@cloudflight/concurrency-utils](api/concurrency-utils)
-- [@cloudflight/logger](api/logger)
-- [@cloudflight/rxjs-read](api/rxjs-read)
+-   [@cloudflight/akita-read](pathname:///api/akita-read/index.html)
+-   [@cloudflight/angular-display](pathname:///api/angular-display/index.html)
+-   [@cloudflight/angular-logger](pathname:///api/angular-logger/index.html)
+-   [@cloudflight/angular-teleport](pathname:///api/angular-teleport/index.html)
+-   [@cloudflight/concurrency-utils](pathname:///api/concurrency-utils)
+-   [@cloudflight/logger](pathname:///api/logger/index.html)
+-   [@cloudflight/rxjs-read](pathname:///api/rxjs-read/index.html)
diff --git a/apps/documentation/tsconfig.app.json b/apps/documentation/tsconfig.app.json
@@ -1,9 +1,11 @@
 {
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "outDir": "../../dist/out-tsc",
-    "types": ["node"]
-  },
-  "exclude": ["jest.config.ts", "**/*.spec.ts", "**/*.test.ts"],
-  "include": ["**/*.ts", "src/.vuepress/config.ts"]
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "outDir": "../../dist/out-tsc",
+        "types": ["node"],
+        "resolveJsonModule": true,
+        "allowSyntheticDefaultImports": true
+    },
+    "exclude": ["jest.config.ts", "**/*.spec.ts", "**/*.test.ts"],
+    "include": ["**/*.ts", "src/.vitepress/config.ts"]
 }
diff --git a/nx.json b/nx.json
@@ -18,26 +18,9 @@
     "affected": {
         "defaultBase": "main"
     },
-    "implicitDependencies": {
-        "tools/scripts/generate-doc.js": "*"
-    },
     "namedInputs": {
         "default": ["{projectRoot}/**/*"]
     },
-    "targetDependencies": {
-        "build": [
-            {
-                "target": "build",
-                "projects": "dependencies"
-            }
-        ],
-        "generate-docs": [
-            {
-                "target": "generate-docs",
-                "projects": "dependencies"
-            }
-        ]
-    },
     "generators": {
         "@nx/angular:application": {
             "style": "scss",
@@ -71,6 +54,12 @@
         },
         "lint": {
             "inputs": ["default", "{workspaceRoot}/.eslintrc.js"]
+        },
+        "build": {
+            "dependsOn": ["^build"]
+        },
+        "generate-docs": {
+            "dependsOn": ["^generate-docs"]
         }
     }
 }
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
     "name": "cloudflight",
-    "version": "0.4.1",
+    "version": "0.4.2",
     "scripts": {
         "build": "nx run-many --target=build --all --parallel",
         "test": "nx run-many --target=test --all --parallel",
@@ -10,7 +10,7 @@
         "postinstall": "husky install && ngcc --properties es2020 browser module main",
         "lint:format": "nx format:check --all",
         "format:staged": "nx format:write --uncommitted",
-        "docs:serve": "nx run apps-documentation:serve"
+        "docs:serve": "vitepress serve apps/documentation/src"
     },
     "private": true,
     "author": "Cloudflight GmbH",
@@ -94,8 +94,9 @@
         "ts-jest": "29.1.0",
         "ts-node": "10.9.1",
         "typedoc": "0.24.6",
-        "typedoc-plugin-markdown": "3.15.3",
+        "typedoc-plugin-markdown": "4.0.0-next.12",
+        "typedoc-vitepress-theme": "1.0.0-next.1",
         "typescript": "4.9.5",
-        "vuepress": "2.0.0-beta.61"
+        "vitepress": "1.0.0-beta.1"
     }
 }
diff --git a/packages/akita-read/README.md b/packages/akita-read/README.md
@@ -23,41 +23,37 @@ You created a Query for your Store that reads the date and formats it using [dat
 
 ```ts
 export class ProductQuery extends Query<ProductState> {
-  constructor(protected store: ProductStore) {
-    super(store);
-  }
+    constructor(protected store: ProductStore) {
+        super(store);
+    }
 
-  readonly expirationDate$ = this.select('expirationDate').pipe(
-    map((date) => format(date, 'dd.MM.yyyy hh:mm'))
-  );
+    readonly expirationDate$ = this.select('expirationDate').pipe(map((date) => format(date, 'dd.MM.yyyy hh:mm')));
 }
 ```
 
 For some reason you figure it would also be good to have access to this in a synchronous way so you add a getter:
 
 ```ts
 export class ProductQuery extends Query<ProductState> {
-  //... other stuff ...
+    //... other stuff ...
 
-  get expirationDate(): string {
-    return format(this.getValue().expirationDate, 'dd.MM.yyyy HH:mm');
-  }
+    get expirationDate(): string {
+        return format(this.getValue().expirationDate, 'dd.MM.yyyy HH:mm');
+    }
 
-  //... other stuff ...
+    //... other stuff ...
 }
 ```
 
 Later you get the requirement that the expiration date always needs to be at the end of the day. So you change your implementation to:
 
 ```ts
 export class ProductQuery extends Query<ProductState> {
-  //... other stuff ...
+    //... other stuff ...
 
-  readonly expirationDate$ = this.select('expirationDate').pipe(
-    map((date) => format(endOfDay(date), 'dd.MM.yyyy hh:mm'))
-  );
+    readonly expirationDate$ = this.select('expirationDate').pipe(map((date) => format(endOfDay(date), 'dd.MM.yyyy hh:mm')));
 
-  //... other stuff ...
+    //... other stuff ...
 }
 ```
 
@@ -68,16 +64,14 @@ But you just introduced a **bug**, because you forgot to change it for the synch
 This is where this wrapper comes into play. Instead of directly selecting/reading the value you can let this library do it for you:
 
 ```ts
-import { readFrom, map } from '@cloudflight/akita-read';
+import {readFrom, map} from '@cloudflight/akita-read';
 
 export class ProductQuery extends Query<ProductState> {
-  constructor(protected store: ProductStore) {
-    super(store);
-  }
+    constructor(protected store: ProductStore) {
+        super(store);
+    }
 
-  readonly expirationDate$ = readFrom(this, 'expirationDate').pipe(
-    map((date: string) => format(date, 'dd.MM.yyyy hh:mm'))
-  );
+    readonly expirationDate$ = readFrom(this, 'expirationDate').pipe(map((date: string) => format(date, 'dd.MM.yyyy hh:mm')));
 }
 ```
 
@@ -88,9 +82,9 @@ declare const productQuery: ProductQuery;
 
 // accessing the value asynchronously
 productQuery.expirationDate$.subscribe({
-  next(expirationDate) {
-    console.log(expirationDate);
-  },
+    next(expirationDate) {
+        console.log(expirationDate);
+    },
 });
 
 // accessing the value synchronously
@@ -101,8 +95,8 @@ Now whenever you change the implementation both ways of accessing will be up-to-
 
 ## Usage
 
-The akita specific functions provided by this library build on the base library [`@cloudflight/rxjs-read`](../rxjs-read/README.md).
-There the base class [`Read`](../rxjs-read/classes/Read.md) and all the operators are defined and reexported in this library for convenience reasons.  
+The akita specific functions provided by this library build on the base library [`@cloudflight/rxjs-read`](../rxjs-read/).
+There the base class [`Read`](../rxjs-read/classes/class.Read.md) and all the operators are defined and reexported in this library for convenience reasons.  
 Even though you can use `@cloudflight/rxjs-read` as a standalone library, it is not recommended, because it heavily goes against the redux concepts on which RXJS is built upon.
 
 ### [Akita-Query](https://opensource.salesforce.com/akita/docs/query)
@@ -111,15 +105,15 @@ To create a Read from a Query you can simply use the `readFrom` function.
 It allows the same selection options like the normal `select` method of the Akita-Query.
 
 ```ts
-import { readFrom } from '@cloudflight/akita-read';
+import {readFrom} from '@cloudflight/akita-read';
 
 export class ProductQuery extends Query<ProductState> {
-  constructor(protected store: ProductStore) {
-    super(store);
-  }
+    constructor(protected store: ProductStore) {
+        super(store);
+    }
 
-  readonly expirationDate$ = readFrom(this);
+    readonly expirationDate$ = readFrom(this);
 }
 ```
 
-For more examples check out the API documentation of [`readFrom`](modules.md#readFrom)
+For more examples check out the API documentation of [`readFrom`](functions/function.readFrom.md)
diff --git a/packages/akita-read/package.json b/packages/akita-read/package.json
@@ -1,6 +1,6 @@
 {
     "name": "@cloudflight/akita-read",
-    "version": "0.4.1",
+    "version": "0.4.2",
     "keywords": [
         "akita-read",
         "akita"