Tech and Tips

Writing documentation like release notes in Word is a pain, especially when you have it within  your project which is under version control.
Diffs between commits are impossible and you risk having 2 people editing the document at the same time and overwriting each others changes (no automatic merge possibility like you have with the code).

The idea is then to use asciidocs to write the documentation and then generate PDF documents from there with some kind of template in order to have a final document which is easy to pass around.

So comes asciidoctor to the rescue, which has a maven plugin allowing us to do everything via maven!

You need this in your pom.xml file:

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <asciidoctor.maven.plugin.version>1.5.3</asciidoctor.maven.plugin.version>
        <asciidoctorj.pdf.version>1.5.0-alpha.11</asciidoctorj.pdf.version>
        <asciidoctorj.version>1.5.4</asciidoctorj.version>
        <jruby.version>1.7.21</jruby.version>
    </properties>

    <build>
        <defaultGoal>process-resources</defaultGoal>
        <plugins>
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>${asciidoctor.maven.plugin.version}</version>
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>${asciidoctorj.pdf.version}</version>
                    </dependency>
                    <!-- Comment this section to use the default jruby artifact provided by the plugin -->
                    <dependency>
                        <groupId>org.jruby</groupId>
                        <artifactId>jruby-complete</artifactId>
                        <version>${jruby.version}</version>
                    </dependency>
                    <!-- Comment this section to use the default AsciidoctorJ artifact provided by the plugin -->
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj</artifactId>
                        <version>${asciidoctorj.version}</version>
                    </dependency>
                </dependencies>
                <configuration>
                    <sourceDirectory>src/main/resources/ReleaseNotes</sourceDirectory>
                    <!-- Attributes common to all output formats -->
                    <attributes>
                        <sourcedir>${project.build.sourceDirectory}</sourcedir>
                    </attributes>
                </configuration>
                <executions>
                    <execution>
                        <id>generate-pdf-doc</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                            <!-- Since 1.5.0-alpha.9 PDF back-end can use 'rouge' as well as 'coderay' source highlighting -->
                            <sourceHighlighter>rouge</sourceHighlighter>
                            <attributes>
                                <pdf-stylesdir>${project.basedir}/src/main/resources/ReleaseNotes/themes</pdf-stylesdir>
                                <pdf-style>my-theme</pdf-style>
                                <icons>font</icons>
                                <tabsize>4</tabsize>
                                <pagenums/>
                                <toc/>
                                <idprefix/>
                                <idseparator>-</idseparator>
                            </attributes>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

If you have an image in src/main/resources/ReleaseNotes/images/image1.png and a theme in src/main/resources/ReleaseNotes/themes/my-theme.yml like this

title_page:
  align: right
  background_image: logo.jpg

page:
  layout: portrait
  margin: [2cm, 1cm, 2cm, 1cm] # top, right, bottom, left
  size: A4
base:
  font_color: #333333
  line_height_length: 17
  line_height: $base_line_height_length / $base_font_size
vertical_rhythm: $base_line_height_length
heading:
  font_color: #333333
  font_size: 17
  font_style: bold
  line_height: 1.2
  margin_bottom: $vertical_rhythm
link:
  font_color: #0e83a4
outline_list:
  indent: $base_font_size * 1.5
header:
  height: 1.5cm
  line_height: 1
  recto_content:
    center: '{document-title}'
  verso_content:
    center: '{document-title}'
footer:
  height: 1.5cm
  line_height: 1
  recto_content:
#    right: '{section-title} | *{page-number}/{page-count}*'
    right: '*{page-number}/{page-count}*'
  verso_content:
#    left: '*{page-number}/{page-count}* | {section-title}'
    left: '*{page-number}/{page-count}*'
image:
  align: center
caption:
  align: center
  font_color: #FF0000
  font_size: 10

You can then write your release notes in asciidocs format in src/main/resources/ReleaseNotes/Release_Notes.adoc, which could like like this:

= Release Notes 1.0.0
My Project
v1.0.0

// variables
:MyProj: My fancy project name


// Settings:
:sectnums:
:toc:
:toclevels: 3
:imagesdir[:imagesdir: images]




[.thumb]
image::image1.png[scaledwidth=20%]

[abstract]


== Introduction

This document contains release notes and change log for releases and patches to {MyProj}. +
 +
The document describes changes, known issues, deliverables and versions of sub components for a single version of the application. +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
,===
*Author*, Bugs Bunny
*Status*, Final
*Approved by*, Daffy Duck
*Version*, 1.0.0
*Created*,  January 14th 2016
*Last changed*, January 19th 2016
,===


<<<

== Revision History

*Only for this release* +
 +
[format="csv", options="header"]
|===
Date, Version, Description, Author
*15.01.2016*,0.1,First draft, Bugs Bunny
*15.01.2016*,0.2,Updates, Daffy Duck
|===

<<<

== Version Description


=== Deliverables (Sub components/Features)

bla bla bla...

<<<


=== Dependencies

+++<span style="color: #FF0000">Just some red text</span>+++ +

=== Comments

Comments comments +
 +
 +
*+++<span style="color: red;">WARNING: red and bold</span>+++* +

Then when you compile your project via maven, you will get a PDF document in target/generated-docs!
It should like like this.


In this example, we use asciidoctor to generate the PDF file so the syntax can be a bit different than plain asciidoc.


References:
AsciiDoc Syntax Quick Reference
http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/

Chapter 10. Text Formatting
http://www.methods.co.nz/asciidoc/chunked/ch10.html

asciidoctor-maven-examples/asciidoctor-pdf-example at master · asciidoctor/asciidoctor-maven-examples
https://github.com/asciidoctor/asciidoctor-maven-examples/tree/master/asciidoctor-pdf-example

asciidoctor/asciidoctor-pdfhttps://github.com/asciidoctor/asciidoctor-pdf

asciidoctor-pdf/theming-guide.adoc
https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc

AsciiDoc Writer’s Guide
http://asciidoctor.org/docs/asciidoc-writers-guide/

Asciidoctor User Manual
http://asciidoctor.org/docs/user-manual/

Asciidoctor Documentation
http://asciidoctor.org/docs/

Differences between Asciidoctor and AsciiDoc
http://asciidoctor.org/docs/asciidoc-asciidoctor-diffs/

AsciiDoc Writer’s Guide
http://asciidoctor.org/docs/asciidoc-writers-guide/