Add Asciidoctor Gradle plugin

GitHub Flavored Markdown does not support the specialized features that
this project requires, such as use of colors and easy conversion to
other file formats. AsciiDoc, like Markdown, uses a readable syntax
that is easy to learn. It is also supported by GitHub preview. In
addition, AsciiDoc supports more features, such as auto-numbering of
sections, auto-generation of table of contents and admonition blocks.
Styling is also possible using custom CSS stylesheets. Furthermore,
AsciiDoc is designed to make it easy to translate documents to other
formats, and Asciidoctor makes it simple for users to generate HTML
files from asciidoc documents.

Converting to PDF:

While Asciidoctor supports conversion to PDF, Asciidoctor PDF is
currently an alpha release and does not support useful features such as
font colors. Styling must also be done separately in an Asciidoctor PDF
theme file, which is different from the CSS used for HTML files.

To convert documentation to PDF format, we suggest using the browser's
'save as PDF' function on the generated HTML files instead.

Stylesheets:

asciidoctor.css is the default stylesheet by Asciidoctor and
gh-pages.css is the customized version used by the documentation.
Having our customizations in a separate file instead of editing the
default stylesheet makes it easy for developers to swap in other
stylesheets which import the default stylesheet, such as those available
at https://github.com/darshandsoni/asciidoctor-skins.

copyStylesheets Gradle task:

Asciidoctor suggests using the resources method to copy additional
resources (in this case, CSS stylesheets) to the build directory.
However, this does not work as Asciidoctor tries to generate the
HTML files before copying the resources, as discussed in
asciidoctor/asciidoctor-gradle-plugin#178.

Let's create a copyStylesheets task to copy the necessary resources
before running Asciidoctor instead, a workaround suggested in
the issue mentioned above.

Asciidoctor attributes:

Even though all AsciiDoc files use the same images directory,
imagesDir attribute must be set in each individual file instead of
in Asciidoctor's attributes. Otherwise, GitHub preview wrongly
links to image.png instead of images/image.png so images are not
displayed in the preview.

build.gradle

@@ -8,6 +8,7 @@
 plugins {
     id "com.github.kt3k.coveralls" version "2.4.0"
     id "com.github.johnrengelman.shadow" version '1.2.3'
+    id 'org.asciidoctor.convert' version '1.5.3'
     id 'application'
 }
 
@@ -182,4 +183,31 @@ nonGuiTests.mustRunAfter headless
 guiTests.mustRunAfter headless
 allTests.mustRunAfter headless
 
-defaultTasks 'clean', 'headless', 'allTests', 'coverage'
+asciidoctor {
+    backends 'html5'
+    sourceDir 'docs'
+    outputDir "${buildDir}/docs"
+
+    attributes linkcss: true,
+               stylesdir: 'stylesheets',
+               stylesheet: 'gh-pages.css',
+               'source-highlighter': 'coderay',
+               icons: 'font',
+               experimental: true,
+               numbered: true,
+               sectlinks: true,
+               idprefix: ''  // for compatibility with GitHub preview
+}
+
+/*
+ * Copies stylesheets into the directory containing generated HTML files as
+ * Asciidoctor does not copy linked CSS files to the output directory when rendering.
+ * This is needed for linked stylesheets and embedded stylesheets which import other files.
+ */
+task copyStylesheets(type: Copy) {
+    from "${asciidoctor.sourceDir}/stylesheets"
+    into "${asciidoctor.outputDir}/html5/stylesheets"
+}
+asciidoctor.dependsOn copyStylesheets
+
+defaultTasks 'clean', 'headless', 'allTests', 'coverage', 'asciidoctor'

docs/TestDocument.adoc

@@ -0,0 +1,60 @@
+= Test Document
+:toc:
+:toc-placement: preamble
+:imagesDir: images
+
+This is a test asciidoc document to check the setup for asciidoc documentation.
+
+== Heading
+
+=== Subheading
+
+.Bulleted lists
+* *bold*
+** _italics_
+*** `code`
+** [red]#red#
+
+.Numbered lists
+. first
+.. first i
+.. first ii
+.. first iii
+. second
+. third
+.. third i
+... third i i
+
+[NOTE]
+====
+This is a note.
+====
+
+[WARNING]
+====
+This is a warning.
+====
+
+[role="details"]
+****
+This is a custom block.
+****
+
+
+****
+This is a sidebar block.
+****
+
+=== Subheading II
+
+This tests line break. +
+This should be on a new line.
+
+http://google.com[This] is a link to an external site.
+
+<<subheading, This>> is a link to the previous section.
+
+image::Architecture.png[title="Architecture diagram", width="400"]
+____
+This is a quote block.
+____

docs/UsingGradle.md

@@ -47,6 +47,11 @@ If we package only our own class files into the JAR file, it will not work prope
   Therefore, we package all dependencies into a single JAR files, creating what is also known as a _fat_ JAR file.
   To create a fat JAR fil, we use the Gradle plugin [shadow jar](https://github.com/johnrengelman/shadow).
 
+## Rendering AsciiDoc files
+
+* **`asciidoctor`**<br>
+  Converts AsciiDoc files in `docs` to HTML format. Generated HTML files can be found in `build/docs`.
+
 ## Running the application
 
 * **`run`** <br>