docs: generate and update API reference for cala.sh (#117)

* feat: add spectaql config to generate API reference

* chore: add API reference, link from the sidebar

* feat: add action to update the API reference

* docs: change cala tagline

* docs: update api reference on published release only

* docs: add rust crate docs to sidebar

* chore: docusaurus update

.github/workflows/website-update-api-reference.yml

@@ -0,0 +1,28 @@
+# website-update-api-reference.yml
+name: Website update API reference
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  update-api-reference:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: DeterminateSystems/nix-installer-action@v12
+      - uses: DeterminateSystems/magic-nix-cache-action@v7
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Build the API reference
+        run: |
+          cd website
+          npm install spectaql
+          npx spectaql spectaql-config.yml -t static -f api-reference.html
+      - name: Deploy the API reference
+        run: |
+          git config --local user.name 'github-actions[bot]'
+          git config --local user.email 'github-actions[bot]@users.noreply.github.com'
+          git add website/static/api-reference.html
+          git commit -m "docs: api reference update: $GITHUB_SHA"
+          git push origin main

website/docusaurus.config.ts

@@ -4,7 +4,7 @@ import type * as Preset from '@docusaurus/preset-classic';
 
 const config: Config = {
   title: 'Cala',
-  tagline: 'A double sided accounting ledger built on PostgreSQL',
+  tagline: 'a powerful open source core banking ledger',
   favicon: 'img/favicon.ico',
 
   // production url

website/package.json

@@ -15,20 +15,20 @@
     "typecheck": "tsc"
   },
   "dependencies": {
-    "@docusaurus/core": "3.3.2",
-    "@docusaurus/preset-classic": "3.3.2",
-    "@docusaurus/theme-live-codeblock": "^3.3.2",
-    "@docusaurus/theme-mermaid": "^3.3.2",
+    "@docusaurus/core": "^3.4.0",
+    "@docusaurus/preset-classic": "^3.4.0",
+    "@docusaurus/theme-live-codeblock": "^3.4.0",
+    "@docusaurus/theme-mermaid": "^3.4.0",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^2.3.0",
     "react": "^18.0.0",
     "react-dom": "^18.0.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.3.2",
-    "@docusaurus/tsconfig": "3.3.2",
-    "@docusaurus/types": "3.3.2",
+    "@docusaurus/module-type-aliases": "^3.4.0",
+    "@docusaurus/tsconfig": "^3.4.0",
+    "@docusaurus/types": "^3.4.0",
     "typescript": "~5.2.2"
   },
   "browserslist": {

website/sidebars.ts

@@ -14,6 +14,16 @@ const sidebars: SidebarsConfig = {
         'demo/check-account-balance',
       ]
     },
+    {
+      type: 'link',
+      label: 'API reference',
+      href: 'https://cala.sh/api-reference.html',
+    },
+    {
+      type: 'link',
+      label: 'Rust crate docs',
+      href: 'https://docs.rs/cala-ledger/latest/cala_ledger/',
+    },
   ],
 };
 

website/spectaql-config.yml

@@ -0,0 +1,11 @@
+introspection:
+  schemaFile: ../cala-server/schema.graphql
+
+info:
+  title: Cala GraphQL API reference
+  description: Get started on [cala.sh/docs](https://cala.sh/docs/)
+
+servers:
+  - url: http://localhost:2252/graphql
+    description: Local dev environment
+    production: false