...
Contributing to Documentation
Within the distribution/docs module, all content files are stored with an .adoc file extension.
.ftl Files
...
.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.
| View file |
|---|
| name | _endpoint-contents-template.adoc |
|---|
| height | 250 |
|---|
|
| View file |
|---|
| name | _plugin-contents-template.adoc |
|---|
| height | 250 |
|---|
|
| View file |
|---|
| name | _transformer-contents-template.adoc |
|---|
| height | 250 |
|---|
|
`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} |
\used Used as a base url placeholder for http urls used in DDF. Use as is in code blocks and pre-formatted text, but make sure to escape the automatic asciidoctor linking in regular text with a backslash \ |
${secure_url} |
\used | Used as a base url placeholder for https urls used in DDF. |
${home_directory} | <DDF_HOME> |
placeholder | Placeholder for DDF home directory under which all system directories and files are found. Downstream projects should set this to reflect that distribution's branding. |
${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 | Allows using the '${variable-name}' syntax in code blocks |
| without accidental filtering/replacement. |
${admin-console} | Admin Console | Standardizes references to the Admin Console. Used in how-tos and procedure instructions to refer to the admin user interface. |
${command-console} | Command Console | Standardizes references to the DDF command line interface. |
Additionally, there is a property for the name of each application within DDF.