# Documentation

# Generating the doc

The approach we have adopted rely on:

# 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/step-by-step' ]
    },
    {
      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:

# 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:

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: Hooks Diagram Template