Skip to content

Home

Jump to bottom
Malke Vu edited this page Mar 23, 2019 · 10 revisions

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:

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.

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.

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

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:

Creative Commons License Agreement
This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

Clone this wiki locally