# 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
- make it with draw.io (opens new window) and store it in this folder
- export it as SVG/PNG in the root assets folder
- reference it in the documentation using a link like this

# mermaid
- install the mermaid CLI (opens new window)
- start from the hooks diagram template file
- 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
- reference it in the documentation using a link like this

The template looks like this: