feat: documentation - POC

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Deploy docs to Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: yarn
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - name: Install dependencies
+        run: yarn install
+      - name: Build with VitePress
+        run: |
+          yarn docs:build
+          touch docs/.vitepress/dist/.nojekyll
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    name: Deploy
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.gitignore

@@ -7,3 +7,5 @@ dist/
 tsconfig.tsbuildinfo
 !babel.config.js
 yarn-error.log
+docs/.vitepress/dist
+docs/.vitepress/cache

docs/.vitepress/config.mts

@@ -0,0 +1,32 @@
+import { defineConfig } from 'vitepress'
+import { transformerTwoslash } from 'vitepress-plugin-twoslash' 
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "Omnibus",
+  description: "Event Bus TypeScript Library",
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Get Started', link: '/quick-start' }
+    ],
+
+    sidebar: [
+      {
+        text: 'Quick Start',
+        items: [
+        ]
+      }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/h-sphere/omnibus' }
+    ]
+  },
+  markdown: {
+    codeTransformers: [
+      transformerTwoslash() 
+    ]
+  }
+})

docs/.vitepress/theme/index.ts

@@ -0,0 +1,12 @@
+// .vitepress/theme/index.ts
+import Theme from 'vitepress/theme'
+import TwoslashFloatingVue from 'vitepress-plugin-twoslash/client' 
+import 'vitepress-plugin-twoslash/style.css' 
+import type { EnhanceAppContext } from 'vitepress'
+
+export default {
+  extends: Theme,
+  enhanceApp({ app }: EnhanceAppContext) {
+    app.use(TwoslashFloatingVue) 
+  },
+}

docs/index.md

@@ -0,0 +1,60 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "Omnibus"
+  text: "Event Bus TypeScript Library"
+  image: 
+    light: ./assets/logo.svg
+    dark: ./assets/logo-light.svg
+    alt: Omnibus Logo
+  tagline: The only event library you will ever need
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /quick-start
+    - theme: alt
+      text: GitHub
+      link: https://github.com/h-sphere/omnibus
+
+features:
+  - title: Cross Platform
+    icon: 🔃
+    details: Omnibus can run on any platform without any additional dependencies
+  - title: TypeScript first
+    icon:
+      src: ./assets/ts.png
+      alt: Type Script
+    details: Every method, event and property is properly typed and inferred from your code
+  - title: Open Sourced
+    icon: 
+      src: ./assets/os.svg
+      alt: Open Source
+    details: Check out the source code, improve, contribute!
+---
+<section class="vp-doc">
+  <div style="max-width: 1152px; margin: 1em auto; padding: 1em;">
+
+## Omnibus 101
+```ts twoslash
+import { BusBuilder, args } from '@hypersphere/omnibus'
+
+const bus = BusBuilder
+  .init()
+  .register('transaction', args<{ amount: number }>())
+  .build()
+
+bus.on('transaction', t => {
+  //                  ^?
+  console.log(t)
+})
+
+bus.trigger('transaction', {
+  amount: 55
+})
+
+```
+
+  </div>
+</section>

docs/quick-start.md

@@ -0,0 +1,39 @@
+# Quick Start
+
+Let's get started with Omnibus library. All core concepts can be learned in 5 minutes!
+
+## Example
+
+```ts twoslash
+const sendLogToAnalyse = (x: any) => { }
+// ---cut---
+import { BusBuilder, args } from '@hypersphere/omnibus';
+
+const bus = BusBuilder
+  .init()
+  .register('log', args<{
+    message: string,
+    severity: 'error' | 'warning' | 'info'
+  }>())
+  .derive('log.error', 'log', (b) => b
+    .filter(log => log.severity === 'error'))
+  .derive('log.warning', 'log', (b) => b
+    .filter(log => log.severity === 'warning'))
+  .derive('log.info', 'log', (b) => b
+    .filter(log => log.severity === 'info'))
+  .build()
+
+// Now we can use our bus
+
+// Registering Event
+bus.on('log.error', e => sendLogToAnalyse(e))
+
+// // Triggering event
+await bus.trigger('log', {
+  message: 'Cannot connect to database',
+  severity: 'error'
+})
+```
+
+The following code sets up an event bus with 5 separate events: `log`, `log.error`, `log.warning`, `log.info` and `log::count`. The last 4 are derived from `log`, meaning that they will get triggered automatically when `log` is triggered. They also use their own builders to filter, map and reduce the data.
+Please note that all the methods and objects are strongly typed and Omnibus will automatically detect proper types for each of the events: you will get proper type checking in all the places.

package.json

@@ -11,10 +11,16 @@
     "@types/jest": "^29.5.11",
     "jest": "^29.7.0",
     "prettier": "3.2.4",
-    "typescript": "5.3.3"
+    "typescript": "5.3.3",
+    "vitepress": "^1.0.0-rc.39",
+    "vitepress-plugin-twoslash": "^0.10.0-beta.9",
+    "@hypersphere/omnibus": "workspace:*"
   },
   "scripts": {
     "compile": "tsc",
-    "test": "jest src/*"
+    "test": "jest src/*",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   }
 }