Explanation of the documentation-in-code build process. Within DDF, user documentation is compiled and published as part of the standard build process. The Distribution module contains the Documentation module which compiles the content, and publishes an html and a pdf version of the docs.

Maven Build Process

The Documentation module is found in the distribution directory. (this pattern should be followed in downstream projects that include documentation with their distribution.)

Plugins

The Maven pom.xml file defines the build process and contains these plugins:

Maven Dependency Plugin: downloads any upstream documentation that needs to be included. Currently DDF uses this to pull in the user docs from the admin console. Downstream distributions will use this to retrieve the DDF documentation adoc files, images, and templates.

Maven Resources Plugin: Uses maven filtering for Text Replacements within all upstream and current project adoc files.

JBake Maven Plugin: Compiles adoc files according to ftl template files into collected adoc file(s).

Asciidoctor Maven Plugin: Converts master adoc file(s) into final html and pdf formats.

Maven Assembly Plugin: Creates zip files of all artifacts:

raw adoc files for import into downstream distributions
image files for import downstream
templates for import downstream
archive of html & pdf documents to be included in product zip file

Build Helper Maven Plugin: Deploys all artifacts to Nexus repository:

All of the above zip files, individually
unzipped versions of html and pdf versions, to be made available for direct download

Directories and Contents

.ftl Files

These files are the freemarker templates used by jbake to generate the finished documentation module.

.adoc Files

Content is maintained in individual adoc files by topic and is contained in the src/main/resources/content . Freemarker templates will include and organize content base on header info with each partial file. The file documentation.adoc is an empty content file that receives the content from all of the templates and is converted to the documentation.html and documentation.pdf finish product files. The partial content files are grouped into

To ensure compatibility with Windows environments, limit subdirectories to 20 characters and adoc files to 35 characters (30 + .adoc extension).

`_<component>-template.adoc` Files

Generic templates for the minimum documentation to be provided when creating new components. These files are not meant to ever be included, but used as baseline when new components are added and need to be documented.

`config.adoc`

A special file containing asciidoctor configuration settings and variable definitions. Currently only one config is used, but others could be added for special use cases.

Asciidoctor Introduction

For more detail on Asciidoctor syntax or to acheive a more specific effect, see the asciidoctor documentation at Asciidoctor docs.

Troubleshooting

These are some common problems that arise within the docs modules that can cause build failures:

Error message Likely cause To fix

prawn exception "cannot fit"

An unclosed table block. This causes the rest of the document to be put into a single table cell, triggering a Prawn exception.

To find the problem, check the html version partially rendered documentation. (It will have failed in the middle of rendering a page). Formatting will look normal until the section after the missing closing table delimiter. Searching for formatting syntax that doesn't render (such as "=== ") will help to narrow the search.

Fix and rebuild.

"Unresolved Directive in ..."

This message will be displayed within the documentation if an `include::` statement does not match the file name.

Check and fix either the statement or the file name.

"section title out of sequence (expected x, got y)"

Asciidoctor enforces a tree structure for section titles and this is caused by a levels being out of order.

this warning can show up in the partial `contents` files even if not out of order. There is a quirk in asciidoctor to show this error if there are duplicate levels at the beginning of a file.

Check section headings to make sure the outline format is enforced

= Page Title (only one allowed)
 
== Major Heading
 
=== Heading
 
==== Sub-heading
 
=== Heading
 
=== Heading
 
== Major Heading