Documentation

The approach we have adopted rely on VitePress to generate the static web site of your app.

Install VitePress

You first need to install vitepress:

$yarn add -D vitepress

And then add the documentation generation scripts to the package.json file:

"scripts": {
  "dev": "vitepress dev",
  "build": "vitepress build",
  "preview": "vitepress preview"
}

Create the following directory structure to store the VuePress stuff:

docs/
|_ .vitepress/
|    |_ config.mjs
|_ package.json
|_ index.md
|....

• .vitepress stores the VitePress configuration.
• index.md is the entry point of your documentation.
• package.json is the Node.js entry point to build the documentation. The file must have the following content:

{
  "name": "skeleton-documentation",
  "type": "module",
  "scripts": {
    "dev": "vitepress dev",
    "build": "vitepress build",
    "preview": "vitepress preview"
  },
  "devDependencies": {
    "keycloak-js": "^23.0.4",
    "lodash": "^4.17.21",
    "moment": "^2.30.1",
    "quasar": "^2.14.3",
    "vitepress": "^1.0.0-rc.40",
    "vitepress-theme-kalisio": "https://github.com/kalisio/vitepress-theme-kalisio"
  }
}

TIP

The structure follows the VitePress directory structure and more information can be found here

Configure VitePress

Edit the config.mjs to configure VitePress.

.vitepress/config.mjs

import { defineConfig } from 'vitepress'

export default defineConfig({
  base: '/skeleton',
  title: 'Skeleton',
  description: 'Skeleton - KDK application template',
  ignoreDeadLinks: true,
  head: [
    ['link', { rel: 'icon', href: 'https://s3.eu-central-1.amazonaws.com/kalisioscope/skeleton/skeleton-icon-color-2048x2048.png' }]
  ],
  themeConfig: {
    logo: 'https://s3.eu-central-1.amazonaws.com/kalisioscope/skeleton/skeleton-icon-color-2048x2048.png',
    nav: [
      { text: 'About', link: '/about/introduction' },
      { text: 'Guides', link: '/guides/introduction' }
    ],
    sidebar: {
      '/about/': getAboutSidebar(),
      '/guides/': getGuidesSidebar()
    },
    socialLinks: [
      { icon: 'github', link: 'https://github.com/kalisio/skeleton' }
    ],
    footer: {
      copyright: 'MIT Licensed | Copyright © 2017-20xx Kalisio'
    },
  },
  vite: {
    optimizeDeps: {
			include: ['keycloak-js', 'lodash'],
		},
		ssr: {
			noExternal: ['vitepress-theme-kalisio']
		}
  }
})

function getAboutSidebar () {
  return [
    { text: 'About', link: '/about/introduction' },
    { text: 'Contributing', link: '/about/contributing' },
    { text: 'License', link: '/about/license' },
    { text: 'Contact', link: '/about/contact' }
  ] 
}

function getGuidesSidebar () {
  return [
    { text: 'Introduction', link: '/guides/introduction' },
    { text: 'Folder Structure', link: '/guides/structure' },
    { text: 'Installation', link: '/guides/installing' },
    {
      text: 'Development',
      collapsed: true,
      items: [
        { text: 'Setup your environment', link: '/guides/development/setup' },
        { text: 'Develop your app', link: '/guides/development/develop' },
        { text: 'Testing your app', link: '/guides/development/test' },
        { text: 'Configure your app', link: '/guides/development/configure' },
        { text: 'Deploy your app', link: '/guides/development/deploy' },
        { text: 'Publish your app', link: '/guides/development/publish' },
        { text: 'Document your app', link: '/guides/development/documentation' },
        { text: 'Use our CLI', link: '/guides/development/kli' },
        { text: 'Tips', link: '/guides/development/tips' },
        { text: 'Troubleshooting', link: '/guides/development/troubleshooting' }
      ]
    },
    {
      text: 'Howtos',
      collapsed: true,
      items: [
        { text: 'Create a service', link: '/guides/howtos/service' },
        { text: 'Distribute a service', link: '/guides/howtos/distribution' },
        { text: 'Manage permissions', link: '/guides/howtos/permissions' },
        { text: 'Add guards', link: '/guides/howtos/guards' },
        { text: 'Create an activity', link: '/guides/howtos/activity' },
        { text: 'Manage collection', link: '/guides/howtos/collection' },
        { text: 'Add tours', link: '/guides/howtos/tours' },
        { text: 'Build a PWA', link: '/guides/howtos/pwa' },
        { text: 'Connect to Keycloak', link: '/guides/howtos/keycloak' },
        { text: 'Connect to a planet', link: '/guides/howtos/planet' }
      ]
    }
  ]
}

Write the documentation

Here are few tips to know when writing the documentation:

• Pages structure: the pages should match the navigation structure you have defined in the config.js file.
• Handling assets: you can simply refer to the asset using relative URLs. Please refer to the Asset Handling page to know more.
• Take advantage of Markdown extensions

Deploy the documentation to the gh-pages

Have a look at our workflow for an example.

.github/workflows/main.yaml

name: ci
on: [ push, workflow_dispatch ]

jobs:
  run_tests:
    name: Run tests
    if: ${{ !contains(github.event.head_commit.message, 'skip tests') }}
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
        with:
          submodules: true
      - name: Init runner
        run: bash ./scripts/init_runner.sh ${{ github.job }}
      - name: Setup workspace
        env:
          KALISIO_GITHUB_URL: ${{ secrets.KALISIO_GITHUB_URL }}
        run: bash ./scripts/setup_workspace.sh -k klifull
      - name: Run tests
        env:
          SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}
        run: bash ./scripts/run_tests.sh -c -r ${{ github.job }}

  additional_tests:
    strategy:
      fail-fast: false
      matrix:
        node: [ 22 ]
        mongo: [ 7 ]
    name: Additional tests
    if: ${{ contains(github.event.head_commit.message, 'additional tests') }}
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
        with:
          submodules: true
      - name: Init runner
        run: bash ./scripts/init_runner.sh ${{ github.job }}
      - name: Setup workspace
        env:
          KALISIO_GITHUB_URL: ${{ secrets.KALISIO_GITHUB_URL }}
        run: bash ./scripts/setup_workspace.sh -k klifull -n ${{ matrix.node }}
      - name: Run tests
        env:
          SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}
        run: bash ./scripts/run_tests.sh -n ${{ matrix.node }} -m ${{ matrix.mongo }}

  build_app:
    name: Build app
    if: ${{ !contains(github.event.head_commit.message, 'skip app') }}
    runs-on: ubuntu-22.04
    strategy:
      fail-fast: false
      matrix:
        node: [ 20 ]
        debian: [ 'bookworm' ]
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
        with:
          submodules: true
      - name: Init runner
        run: bash ./scripts/init_runner.sh ${{ github.job }}
      - name: Setup workspace
        env:
          KALISIO_GITHUB_URL: ${{ secrets.KALISIO_GITHUB_URL }}
        run: bash ./scripts/setup_workspace.sh -k kli
      - name: Build app
        env:
          SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}
        run: bash ./scripts/build_app.sh -p -r ${{ github.job }} -n ${{ matrix.node }} -d ${{ matrix.debian }}

  build_docs:
    name: Build docs
    if: ${{ startsWith(github.event.head_commit.message, 'docs:') || contains(github.event.head_commit.message, 'build doc') }}
    runs-on: ubuntu-22.04  
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
        with:
          submodules: true
      - name: Init runner
        run: bash ./scripts/init_runner.sh ${{ github.job }}
      - name: Setup workspace
        env:
          KALISIO_GITHUB_URL: ${{ secrets.KALISIO_GITHUB_URL }}
        run: bash ./scripts/setup_workspace.sh -k nokli
      - name: Build docs
        env:
          SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}
        run: bash ./scripts/build_docs.sh -p -r ${{ github.job }}

Working with diagrams

We use two distinct tools to work with diagrams:

• draw.io a complete editor to create well known diagrams
• mermaid which allows you to generate diagrams from a simple text definition. We mainly use mermaid to create the hooks diagrams.

To be able to include the diagrams within the documentation, we adopted the following methodology:

Draw.io

1. make it with draw.io and store it in this folder
2. export it as SVG/PNG in the root assets folder
3. reference it in the documentation using a link like this ![My legend](https://raw.githubusercontent.com/kalisio/kdk/master/images/my-diagram.png)

mermaid

1. install the mermaid CLI
2. start from the hooks diagram template file

.github/workflows/main.yaml

graph TB
    beforeAll{before all}
    bahook(ba-hook) --> beforeAll

    afterAll{after all}
    afterAll --> aahook(aa-hook)

    beforeAll --> bfhook(bf-hook)
    bfhook -->|before| FIND[FIND]
    FIND -->|after| afhook(af-hook)
    afhook --> afterAll
    
    beforeAll --> bghook(bg-hook)
    bghook -->|before| GET[GET]
    GET -->|after| aghook(ag-hook)
    aghook --> afterAll

    beforeAll --> bchook(bc-hook)
    bchook -->|before| CREATE[CREATE]
    CREATE -->|after| achook(ac-hook)
    achook --> afterAll

    beforeAll --> buhook(bu-hook)
    buhook -->|before| UPDATE[UPDATE]
    UPDATE -->|after| auhook(au-hook)
    auhook --> afterAll

    beforeAll --> bphook(bp-hook)
    bphook -->|before| PATCH[PATCH]
    PATCH -->|after| aphook(ap-hook)
    aphook --> afterAll

    beforeAll --> brhook(br-hook)
    brhook -->|before| REMOVE[REMOVE]
    REMOVE -->|after| arhook(ar-hook)
    arhook --> afterAll

    linkStyle default stroke-width:2px,fill:none,stroke:black
    classDef hookClass fill:#f96,stroke:#333,stroke-width:2px
    class bahook,aahook,bfhook,afhook,bghook,aghook,bchook,achook,buhook,auhook,bphook,aphook,brhook,arhook hookClass
    classDef operationClass fill:#9c6,stroke:#333,stroke-width:2px
    class FIND,GET,CREATE,UPDATE,PATCH,REMOVE operationClass

3. output the SVG/PNG file in the root assets folder using mmdc -i ./my-hooks-diagram.mmd -t neutral -b transparent -o my-hooks-diagram.svg
4. reference it in the documentation using a link like this ![My legend](https://raw.githubusercontent.com/kalisio/kdk/master/images/my-diagram.png)

The template looks like this: