Documentation / Tutorials

Writing Documentation

GraphStream uses GitHub Pages to manage its documentation. The GitHub Pages process combines a git repository containing your documentation and the Jekyll platform to create a website from this documentation. The latter is written using the Markdown markup language (but you can use HTML directly). For example, just have a look to the source of this tutorial.

Writing Your Document

Preliminaries

First you have to decide a few things :

  1. Title of your document ;
  2. Where your document belongs into the documents hierarchy, it will be called document path. This one belongs to the Tutorials part, with /doc/Tutorials/ as path.

File Name

File containing your document should be named after the document title, with no space, only word characters, and - between words. Use the .md extension and put your file inside the directory linked to your document path.

Document Headers

Jekyll uses file headers to identify which files should be processed. Headers should start at the very beginning of the file (first characters) with --- on a single line, and have to end with the same --- chain. Between these two lines will come some meta-informations about your document. There is one information by line, on the form key: value.

The basic header you will have to set is :

---
title: Your Document Title
docpath: YourDocumentPathName|/your/document/path
layout: documentation
permalink: /your/document/path/Your-Document-Title/
---

The layout information is used to tell Jekyll the template that will be used. You can add other informations like author.

Referencing your document

We have to tell files contained in each section. Jekyll will have later a feature called collections, but this is actually unstable. So you have to do the job.

List of files in a section are stored as data. Jekyll stored these data, which are YAML file, in the _data directory. If we consider the Tutorials section, we can find the _data/doc/tutorials.yml file, listing all document in this section. Name convention is :

  • to use lower case ;
  • to use snake_case to format each path component ;
  • to use - between components, ending the file with .yml.

For example, if we consider the FAQ section about the graph class /doc/FAQ/The-Graph-Class, we should put list of files in this section in the data file named _data/doc/faq-the_graph_class.yml.

Have a look to the existing files to become familiar with the YAML syntax. There are two main lists in these files, paths and documents. The former to reference subsections, and the latter to reference documents. Inside these lists, each entry has two items, title and href.

Testing Locally

Before performing a pull request on the git repository, you should test your modifications locally. You will need the ruby tool called gem.

Install bundler

Bundler will help us to manage the ruby part of this. You can install it using gem install bundler. Then, inside the root of the git repository, create a file called Gemfile and put the following content inside :

source 'https://rubygems.org'
gem 'github-pages'

You may have to install other gems like rb-pygments and jekyll-redirect-from. These gems are used by the GraphStream website.

Run Jekyll

To launch your Jekyll server, just run bundle exec jekyll serve. It will generating the website (in the _site directory), and create and http server at http://localhost:4000. Jekyll is listening to file changes, so you should not have to restart it after making some changes.