Home

How to build the documentation

Install Maven

Maven will be used to build the documentation from Docbook (module org.restlet.tutorial.docbook). This tool is available at the address: http://maven.apache.org/.

Install Node and node-markdown-to-docbook

These tools will be used to convert the documentation from Markdown to Docbook formats (module org.restlet.tutorial.markdown to module org.restlet.tutorial.docbook).

These tools are available at the following addresses:

• Node: http://nodejs.org/
• node-markdown-to-docbook: https://github.com/Kami/node-markdown-to-docbook/

Note: you need to patch the node-markdown-to-docbook tool not to set some XML attributes on root elements of XML files (line 61 for version 0.1.1).

attrib = {/*'xmlns': 'http://docbook.org/ns/docbook',
          'xmlns:xlink': 'http://www.w3.org/1999/xlink',
          'xmlns:xi': 'http://www.w3.org/2001/XInclude',
          'xmlns:svg': 'http://www.w3.org/2000/svg',
          'version': '5.0',*/
          'id': id};

Convert documentation from Markdown to Docbook

Create a script for all directories:

#!/bin/sh

M2D_TOOL=/.../repositories/git/node-markdown-to-docbook
MD_SRC=/../repositories/git/restlet-tutorial/modules/org.restlet.tutorial.markdown
DCBK_SRC=/../repositories/git/restlet-tutorial/modules/org.restlet.tutorial.docbook

#Create docbook
$M2D_TOOL/bin/markdown-to-docbook -i $MD_SRC/02_Server_Side/01_Server_Application_Foundations/ -o $DCBK_SRC/src/docbkx/tutorial/servers/foundations/
$M2D_TOOL/bin/markdown-to-docbook -i $MD_SRC/02_Server_Side/02_Server_Resources/ -o $DCBK_SRC/src/docbkx/tutorial/servers/resources/
$M2D_TOOL/bin/markdown-to-docbook -i $MD_SRC/02_Server_Side/03_Representations/ -o $DCBK_SRC/src/docbkx/tutorial/servers/representations/
$M2D_TOOL/bin/markdown-to-docbook -i $MD_SRC/02_Server_Side/04_Server_Deployment/ -o $DCBK_SRC/src/docbkx/tutorial/servers/deployments/
$M2D_TOOL/bin/markdown-to-docbook -i $MD_SRC/02_Server_Side/05_Server_Advanced/ -o $DCBK_SRC/src/docbkx/tutorial/servers/advanced/
$M2D_TOOL/bin/markdown-to-docbook -i $MD_SRC/02_Server_Side/06_Use_Cases/ -o $DCBK_SRC/src/docbkx/tutorial/servers/use-cases/

and run it.

Build html and pdf documentations

Go into the org.restlet.tutorial.docbook and type:

$ /(...)/apache-maven-2.0.10/bin/mvn site

The documentations (html and pdf) are then available in the target/site/tutorial directory.