Documentation

Generating the doc

The approach we have adopted rely on:

• VuePress (opens new window) to generate the static web site
• the VuePress plugin pwa (opens new window) to enable the site to be refreshed when the content changed
• our own theme (opens new window). This theme overides the VuePress default theme in adding the Kalisio logo instead of the Adds.

Install VuePress

You first need to add the dependencies in the project:

$yarn add -D vuepress
$yarn add -D http://github.com/kalisio/vuepress-theme-kalisio#1.3.0

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

"scripts": {
  "docs:dev": "vuepress dev docs",
  "docs:build": "vuepress build docs"
}

Create the following directory structure to store the VuePress stuff:

docs/
|_ .vuepress/
|    |_ public/
|    |    |_ manifest.json
|    |_ config.js
|_ assets/
|_ package.json
|_ README.md
|....

• .vuepress stores the VuePress configuration.
• assets stores the resources (images, diagrams...) you want to use in your documentation.
• README.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": "docs",
  "scripts": {
    "dev": "vuepress dev .",
    "build": "vuepress build ."
  },
  "devDependencies": {
    "vuepress": "^1.7.1",
    "vuepress-theme-kalisio": "https://github.com/kalisio/vuepress-theme-kalisio#v0.1.0"
  }
}

TIP

The structure follows the VuePress directory structure and more information can be found here (opens new window)

Configure VuePress

Edit the config.js to configure VuePress. We usually have this kind of configuration:

module.exports = {
  base: '/kdk/',
  port: 8888,
  title: 'KDK',
  description: 'The Kalisio Development Kit',
  head: [
    ['link', { rel: 'icon', href: `https://s3.eu-central-1.amazonaws.com/kalisioscope/kdk/kdk-icon-64x64.png` }],
    ['link', { rel: 'manifest', href: '/manifest.json' }]
  ],
  theme: 'kalisio',
  themeConfig: {
    nav: [
      { text: 'About', link: '/about/' },
      { text: 'Guides', link: '/guides/' },
      { text: 'Architecture', link: '/architecture/' },
      { text: 'API', link: '/api/' },
      { text: 'Tips', link: '/tips/' },
      { text: 'Tools', link: '/tools/' }
    ],
    sidebar: {
      '/about/': getAboutSidebar(),
      '/guides/': getGuidesSidebar(),
      '/architecture/': getArchitectureSidebar(),
      '/api/': getAPISidebar(),
      '/tips/': getTipsSidebar(),
      '/tools/': getToolsSidebar()
    }
  }
}

function getAboutSidebar () {
  return [
    '',
    'roadmap',
    'contributing',
    'license',
    'contact'
  ] 
}

function getGuidesSidebar () {
  return [
    '',
    { 
      title: 'The Basics',
      children: [ 'basics/introduction' ]
    },
    {
      title: 'Development',
      children: ['development/setup', 'development/develop', 'development/test', 'development/configure', 'development/deploy', 'development/publish' ] 
    }
  ]
}

function getArchitectureSidebar () {
  return [
    '',
    'main-concepts', 
    'global-architecture', 
    'component-view',
    'data-model-view'
  ]
}

function getAPISidebar () {
  return [
    '',
    {
      title: 'core',
      children: [ 'core/', 'core/application', 'core/services', 'core/hooks', 'core/components', 'core/mixins' ]
    },
    {
      title: 'map',
      children: [ 'map/', 'map/services', 'map/hooks', 'map/components', 'map/mixins', 'map/map-mixins', 'map/globe-mixins' ]
    }
  ]
}

function getTipsSidebar () {
  return [
    '',
    'app-development',
    'mobile-configuration'
  ]
}

function getToolsSidebar () {
  return [
    '',
    'cli',
    'browsers',
    'documentation',
    'infrastructure'
  ]
}

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 (opens new window) page to know more.
• Take advantage of Markdown extensions (opens new window)

Deploy the documentation to the gh-pages

Add the following lines to your .travis.yml file:

  - stage: DOCS
    language: node_js
    node_js:
    - '8'
    install: true
    script:
    - cd docs && yarn install && yarn build
    deploy:
      provider: pages
      local-dir: docs/.vuepress/dist
      skip-cleanup: true
      github-token: $GITHUB_TOKEN  
      keep-history: true
      on:
        branch: master

TIP

You must set the secure variable GITHUB_TOKEN in your Travis CI project settings

Working with diagrams

We use two distinct tools to work with diagrams:

• draw.io (opens new window)] a complete editor to create well known diagrams
• mermaid (opens new window) 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 (opens new window) 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 (opens new window)
2. start from the hooks diagram template file
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: