abhaychandel/devon-docgen

Documentation generator that can generate a complete and self-contained documentation as PDF, ePub and HTML from Asciidoc wiki pages.

Devonfw Documentation Generator

DocGen is a tool that can generate a complete and self-contained documentation as PDF, ePub and HTML from Asciidoc wiki pages.

Features

With DocGen you can

• maintain 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 links between wiki pages into document internal links

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

Setup

1. Clone your github wiki using git to your local machine

2. Create a pom.xml in the cloned wiki directory with the following content:

   <project xmlns="http://maven.apache.org/POM/4.0.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
   
     <modelVersion>4.0.0</modelVersion>
     <parent>
       <groupId>com.devonfw.tools</groupId>
       <artifactId>devon-docgen</artifactId>
       <version>1.0.0</version>
     </parent>
     <groupId>my.group.id</groupId>
     <artifactId>my-artifact-id</artifactId>
     <version>1.0.0-SNAPSHOT</version>
     <packaging>jar</packaging>
     <name>My Cool Wiki</name>
   
     <properties>
       <docgen.wiki.page>my-main-page</docgen.wiki.page>
     </properties>
   
     <!-- run "mvn package" and get the PDF result in target/generated-docs/*.pdf -->
   
   </project>

3. Add, commit and push it to github:

   git add pom.xml
   git commit -m "added pom.xml for docgen"
   git push

4. Optional custom theme: You can develop your own style by using the asciidoctor facilities. Therefore create your own theme in the path theme/custom-theme.yml and also push it to the wiki git repo.

Usage

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

mvn clean package

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

If you want to deploy your documentation to maven central run:

mvn deploy -P oss

Guidelines

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

• Maintain the documentation as collection of wiki pages.

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

• 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

• Start every page with the following AsciiDoc header:

  :toc: macro
  toc::[]
  :idprefix:
  :idseparator: -

• 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 only use 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 clone the wiki with git and use an AsciiDoc editor tool.

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

• 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"]

• For devonfw the 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 documentation (motivation and general goals).

  • devon-* 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.

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.

AsciiDoc Tools

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 for IntelliJ

• AsciiDoc for VS Code

• Asciidoc for Firefox

• Asciidoc for Chrome

• Asciidoc preview for Atom and Asciidoc language for Atom

• Asciidoc for Brackets