Home

Table of Contents

• Devonfw Documentation Generator
  • Features
  • Usage
  • Guidelines
  • Tooling
    • Editing asciidoc local with live preview
    • Editing asciidoc with local wiki emulation

Devonfw Documentation Generator

Here you find the instructions in how to use the devon DocGen tool.

Features

With DocGen we can

• maintain our documentation on github wiki as individual pages using asciidoc based on our guidelines.

• generate a single and self-contained document as PDF, ePub or HTML from it

• convert wiki links into document internal links

• have a single table of contents per complete document as well as per wiki page

Usage

To start the generation manually you need to clone the wiki with the documentation to generate. Then open a command shell in the cloned project and call:

mvn clean package

Then you will find the result in target/generated-docs/.

Guidelines

In order to make DocGen work properly we follow these guidelines:

• We maintain the documentation as collection of wiki pages.

• For the wiki usage we link (important) pages in the sidebar for navigation.

• We use AsciiDoc for all wiki pages. This is not the default on github. Always switch Edit mode to AsciiDoc when creating new wiki pages.

• For help on the syntax consult the writers guide and the cheatsheet

• We start every page with the following skeleton/template:

  :toc: macro
  toc::[]
  :idprefix:
  :idseparator: -
  = Title
  
  Your content

• Wiki pages belong to categories that are also reflected by a naming convention

  • coding-* is used for pages about general aspects to development and writing code.

  • guide-* is used for pages that act as a guide to a specific topic. It describes what to do and how to do it for that topic from the perspective of a developer.

  • alternative-* is used for pages that are not part of the suggested standard but are commonly used or popular alternatives to a proposed standard solution. Such page explains how to use such an alternative solution.

  • architecture is reserved for the architecture documentation.

  • introduction-* is used for pages that are part of the introduction into the OASP documentation (motivation and general goals).

  • devonfw-* is used for pages that are about the devonfw itself and will not be part of the official documentation.

  • tutorial-* is used for pages that are part of the tutorials.

• To include images you need to follow this rules:

  • The best choice for high quality rendering is SVG. As the wiki does not create mimetypes you have to put the image on the github pages.

  • You have to set the size so it gets properly rendered in the PDF. The width value to make it fit properly on the PDF page is 450:

    .Image Title
    image::http://devonfw.github.io/devon4j/images/MyImage.svg["alt-text", width="450", link="http://devonfw.github.io/devon4j/images/MyImage.svg"]

• In order to make internal links work both in wiki as well as in generated documentation (PDF, ePub, HTML) you need to stick to this rules:

  • Do not use special characters (dot, ampersand, etc.) in section titles (use plain text e.g. "My Section")

  • If you link to a section, you simply use the section title in lower case with hyphens instead of spaces (e.g. "my-section"). Within the same wiki page you use xref (e.g. xref:my-section[link title]) and between wiki pages you use link (e.g. link:guide-my-topic#my-section[link title]).

  • In case you want to reference the top-level section of a wiki page you need to use link without a section reference (e.g. link:guide-my-topic[link title]) and NOT xref even if you place the link within the same wiki page.

  • From wiki pages included in the generated documentation (all official parts such as guides) only link via link: to other wiki pages that will also be part of the generated documentation. Otherwise you would produce dead links.

• For editing larger files and offline work we recommend to checkout the wiki with git and use AsciiDocFx as editor.

• You need to ensure that the files use UTF-8 as encoding.

Tooling

Our DocGen tool is technically based on the following tools:

• maven

• asciidoctor

  • via asciidoctor-maven-plugin

• docbook

  • via docbkx-maven-plugin

  • using docbook XSL distribution

• ant

  • via maven-antrun-plugin

This setup was inspired by spring-boot-docs and improved for link processing, etc. Feel free to get inspired here or copy the entire solution if you like it. Thanks to all authors of the actual tools and to spring-boot for making this great DocGen happen.

Editing asciidoc local with live preview

You can checkout a github wiki as a git repository and edit it with an editor of your choice. For this we recommend the following tools:

• AsciiDocFx

• Asciidoc Preview for Firefox

• Asciidoc Preview for Chrome

• Asciidoc Preview for Atom and Asciidoc language for Atom

• Asciidoc Preview for Brackets

Editing asciidoc with local wiki emulation

If you want to edit your wiki locally without intefere with your real wiki, then please take a look at gollum. Gollum is a git-based wiki, which can either be used on a linux machine or in a docker container. This github wikis are somehow based on the same technology as gollum.

• Installation

Caution

When encounter Gem:MissingSpecVersionError then you need to download a specific version gem install <gem_name> -v <version>

• Running

• Configuration Options

• Docker

  • Base image from the official Ruby repo on Docker Hub

  • Content of Dockerfile

        FROM ruby
        RUN apt-get -y update && apt-get -y install libicu-dev cmake && rm -rf /var/lib/apt/lists/*
        RUN gem install github-linguist
        RUN gem install gollum
        RUN gem install asciidoctor # mandatory
        RUN gem install org-ruby  # optional
        WORKDIR /wiki
        ENTRYPOINT ["gollum", "--port", "80"]
        EXPOSE 80

Note	Working directory of the docker container is /wiki Default port is 80

• Building the Docker image

  • docker build -t gollum . will work

• Running the Docker Container

  • docker run -v `pwd`:/wiki -p 4567:80 gollum on Linux

  • docker run -v C:\Users\MyUser\Desktop\my-windows-wiki:/wiki -p 4567:80 gollum on Windows with Docker Desktop

  • docker run -v //c/Users/MyUser/Desktop/my-windows-wiki:/wiki -p 4567:80 gollum on Windows with Docker Toolbox

  • For Docker Compose:

         version: '3'
         services:
            devonfw-wiki:
                volumes:
                - '<path>:/wiki'
                ports:
                - '4567:80'
                image: gollum

Note	$Env:COMPOSE_CONVERT_WINDOWS_PATHS=1 must be set by a Windows Powershell Otherwise your volume will not bind in the container Reference