dokkit [Ruby Documentation toolKit]

home » documentation » tutorials » quickstart

Quickstart with dokkit

This tutorial explains the basic steps to take in order to build your first documentation environment with dokkit. In this tutorial we assume that you are using a linux operating system and that you have dokkit (version >= 0.4.0) installed on it.

For further informations about dokkit installation please refer to this page.

Step 1: Create the documentation environment

In a terminal execute:

dokkit simple

This command will create a directory named simple. Now cd into the directory just created and do ls to see how the model is organized.

Step 2: Configure the documentation environment

Configuring the documentation environment you can decide, among other things, which document source files to include in the building process and which to exclude. For example, to avoid rendering all document files ending with .draft extension, open setup/setup.rb and add this line in the Container initialization code:

c.documents.exclude('*.draft')

Step 3: Edit documentation source files

Once you are in simple directory, cd in doc/pages.

Here you will find the document source file simple.deplate. Starting from this file, dokkit will generate the final document in html, latex and plain text format.

The file simple.deplate has been written using the deplate wiki syntax. Feel free to modify it using a text editor. Consider this file as a good start to learn the basic deplate syntax.

The header of simple.deplate contains some configuration parameters for the document. For example, to change the output format of the document, change the value of format key. Actually, deplate filter produces output in html, latex and plain text format.

Step 4: Generate the documentation

In the simple directory (or in any subdir contained in it) execute the command:

rake

This command will generate, in the output/ directory, the html, latex and plain text version of your document.

Step 5: Configure your document

You can configure your document

Note that if one ore more configuration files are present, the resulting configuration is the mixing of all configuration files. This mixing is done by merging all configuration files following the order given below:

  1. common configuration files (i.e. COMMON.yaml)
  2. configuration file in doc/configs with the same name of the processed document (i.e. doc/configs/simple.yaml)
  3. configuration file in the same directory in which the processed document is and with the same name of the document (i.e. doc/pages/simple.yaml)
  4. configuration in the header of the processed document (i.e. doc/pages/simple.deplate)