Kura Github Documentation

Kura documentation

Our current documentation sources are stored in the docs-develop branch and published through the gh-pages branch.

You can navigate the documentation at: https://eurotech.github.io/docs-guide

We're using several tools for building Kura User Documentation:

• mkdocs: the main tool to generate the static website
• mkdocs-material: the used material-style theme
• mike: the versioning tool, based on mkdocs

Refer to the docs-develop branch README file for additional informations.

Legacy documentation

The old documentation is stored in the gh-pages-legacy branch. Here follows the structure and conventions for the legacy documentation.

Github Pages

Github allows you to create a website for your project using a special domain ([account_name].github.io/[project]). The website can be any static HTML/Javascript page. However, Github also supports Jekyll, which is the engine behind their Wiki pages. Jekyll has been primarily used by bloggers, but can also be leveraged for versioning any documentation.

Environment Setup

Github web pages operate by scanning the repository for a special branch (gh-pages). If this branch is found, it will attempt to render the content as HTML. This branch, however, is an "orphan branch" and is not linked to the existing source code of the other branches. For this reason, you should first create a new directory for the repository, then create a fresh clone.

    mkdir ~/dev/kura_github_pages
    cd ~/dev/kura_github_pages
    git clone https://github.com/eclipse/kura.git -b gh-pages
    cd kura

When working with this branch, make sure to do all pulls and pushes to 'origin gh-pages' to prevent conflict with the main source code branches.

Working with Jekyll

Directory layout

The majority of directories don't need to be touched. The important directories are:

• _posts - This directory contains all the markdown documents. Within this directory you will see subdirectories for each of the sections on the documentation website (conf, intro, etc.). Relevant documentation should be placed in the correct subfolder.
• _drafts - This directory contains all un-published markdown documents. This is where you should write your documents that will be reviewed. Once reviewed, they will be moved to the _posts directory.
• assets - This directory contains the images directory, which is where all document images should be placed.

The Markdown files

The markdown files are no different than normal, but the headers must be present in each document, including drafts. The headings have the form:

---
layout: post
title: "First Kura Solution"
categories: [prog]
date: 2017-05-03 16:22:00
---
* Placeholder for TOC, this line will not appear on site.
{:toc}

The meaning of the individual lines are:

• layout - This specifies the CSS to be applied to the page. For now, "post" can always be used.
• title - This will be the title displayed both in the browsing menu and the page header.
• categories - This indicates in which section the document should reside. The options are listed below. New sections can be added if needed into the _config.yml file.
  • intro - Introduction
  • doc - Documentation
  • ref - Management
  • tut - Tutorial
  • qa - Quality Assurance
• date - The date is actually used to specify the order in which the documents appear in the navigation menu. Newer dates appear at the top of the list while older dates appear at the bottom. See existing documents on how to structure the date.
• {:toc} - This is a convenience function to automatically create a table of contents for your article. It is optional, but recommended.

Running the server

To install Jekyll, refer to https://help.github.com/articles/using-jekyll-with-pages/.

You view the repository on your local machine by running:

    bundle exec jekyll server --baseurl="" --watch

This will start the server on port 4000 of your local machine. Any changes made to the underlying documents will be automatically updated on the server (browser refresh is needed). You can also start the local server with this command:

    bundle exec jekyll server --baseurl="" --watch --drafts

This will include any documents located in the _drafts folder and is useful when editing a new document.