Contributing to Documentation

Within the distribution/docs module, all content files are stored with an .adoc file extension.

.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.

Text Replacements

DDF has several conditional text snippet defined in the top-level pom.xml file. These enable quick substitutions and consistent usage throughout the documentation. These follow the standard maven properties syntax: ${term}. Use these where appropriate in place of hard-coding these values. These are the current definitions and use cases for DDF.

Property	DDF Value	Usage Notes
`${branding}`	`DDF`	Project Name. Use this anywhere a downstream project might change the value to its name.
`${branding-lowercase}`	`ddf`	Used if project name should be lowercase.
`${ddf-branding}`	`DDF`	Used in places where the name should not change in downstream projects. (Custom distributions will need to define this property within the pom.xml file.
`${ddf-branding-lowercase}`	`ddf`	Similar to above, this is for lowercase and unchanged downstream
`${ddf-branding-expanded}`	`Distributed Data Framework`	Useful for instances where the full project name should be spelled out, instead of the acronym.
`${public_url}`	`\http://{FQDN}:{PORT}`	used as a base url placeholder for http urls used in DDF
`${secure_url}`	`\https://{FQDN}:{PORT}`	used as a base url placeholder for https urls used in DDF
`${home_directory}`	`<DDF_HOME>`	placeholder for DDF home directory under which all system directories and files are found.
`${at-symbol}`	`@`	'@' is an escape character for maven filtering. Use this property if '@' appears on the same line as other filtered properties.
`${variable-prefix}`	`${`	allows using the '${variable-name}' syntax in code blocks without accidental filtering/replacement.

Additionally, there is a property for the name of each application within DDF.