...
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
...
| 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.
| Check section headings to make sure the outline format is enforced
|