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: http://eclipse-kura.github.io/kura/

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.

Github Docs Automations

This repository leverages the automation provided by Github actions for automatically building and deploying the documentation to Github pages.

The actions can be found in the .github/workflows folder of this repository:

• backport.yml: Backport automation action.
• build-deploy-docs.yml: Documentation build and deploy automation action.
• pr-lint.yml: GitHub Action that ensures PR titles match the Conventional Commits specification.

Some more details about the automations can be found in the following paragraphs.

Building and deploying

The Github "Build and deploy" is responsible for building the documentation sources and deploying them on the gh-pages branch.

The action expects the documentation for the latest version of the software to be on its own branch named docs-develop. Older, already released versions, should stay on docs-release-[major].[minor] named branches (which should be child branches of docs-develop). For example we expect to see the following branches on a repository:

$ git branch --list "docs*"
docs-develop
docs-release-5.1
docs-release-5.1

The Github action will use the branch name for determining and deploying the documentation to its respective version.

Whenever a change on docs-develop and docs-release-* branches is detected the Github action will kick-off, installing the dependencies listed in the requirements.txt file, building the documentation and deploying it to gh-pages leveraging mike.

After that the pages-build-deployment action will take care of serving the page on Github pages.

Note: The automation expects the requirements.txt file to contain the mkdocs, mike and mkdocs-material package version to be installed and any additional plugin for mkdocs used by the documentation.

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.