okvee / tscfg-docgen

Tools for automatic documentation generation from typesafe config configurations

tscfg-docgen

Tools for automatic documentation generation from typesafe config configurations.

Contents

• 1   Main features
• 2   Installation
  • 2.1   Using the core library
  • 2.2   Using Maven plugin
• 3   Usage
  • 3.1   Maven plugin setup
  • 3.2   Configuration options
  • 3.3   Examples
• 4   Substitutions

1   Main features

• Documentation generated using predefined FreeMarker templates
• Ability to use custom templates
• Injection of documentation into existing files
• Prefix-based grouping of configuration keys for better structure
• Generated documentation is environment-agnostic
• Maven plugin

2   Installation

2.1   Using the core library

<dependency>
    <groupId>io.github.okvee</groupId>
    <artifactId>tscfg-docgen-core</artifactId>
    <version>x.y.z</version>
</dependency>

2.2   Using Maven plugin

<plugin>
    <groupId>io.github.okvee</groupId>
    <artifactId>tscfg-docgen-maven-plugin</artifactId>
    <version>x.y.z</version>
</plugin>

3   Usage

3.1   Maven plugin setup

<plugin>
    ...
    <executions>
        <executions>
            <id>gen-docs</id>                 (1)
            <phase>process-resources</phase>  (2)
            <goals>
                <goal>generate-docs</goal>    (3)
            </goals>
        </executions>
    </executions>
</plugin>

1. A unique ID of this execution
2. Phase in which the execution should take place (by default, this is site)
3. Goal to be executed (currently, generate-docs is the only supported goal)

3.2   Configuration options

All supported configuration options will be demonstrated using maven plugin configuration. The same set of options can be used when working with the core library directly.

inputFilePattern

Pattern used to identify configuration files to read the configuration from (see FileSystem.getPathMatcher(String) for pattern syntax information). Defaults to glob:/**/src/main/resources/reference.conf (This pattern matches reference.conf files in all (sub)directories, i.e. even in sub-modules in case the module using the plugin has some. This makes it possible to generated one global configuration documentation for an entire multi-module project).

outputFile

Path to the file that will contain generated documentation. Defaults to ${basedir}/config.md.

overwriteExisting

Indicates whether an already existing output file can be overwritten. Defaults to false.

templateName

Name of the predefined template to use. This must be one of the templates found in templates directory (name of the template file without .ftl extension). Defaults to markdown-gitlab.

customTemplateFile

Path to a custom FreeMarker template file. If set, this custom template file will be used instead of the predefined template specified by templateName option.

injectGeneratedDocs

This option allows "injecting" the generated configuration to an already existing file without overwriting its original contents. Also see injectionStartPlaceholder and injectionEndPlaceholder options. Defaults to false.

injectionStartPlaceholder

In case injectGeneratedDocs is true, this option's value is used to identify a line in the output file which marks the beginning of the area where generated documentation will be injected. Defaults to <!-- tscfg-docgen-start -->.

injectionEndPlaceholder

In case injectGeneratedDocs is true, this option's value is used to identify a line in the output file which marks the end of the area where generated documentation will be injected. Defaults to <!-- tscfg-docgen-end -->.

topLevelNamespace

Determines top-level namespace (or prefix) of all configuration keys. When specified, each configuration key can be displayed without this top-level namespace prefix in the generated documentation to avoid repeating the prefix with every configuration key. This setting can only be used when all configuration keys belong to the same top-level namespace.

ignoredPrefixes

In order to exclude some of the configuration keys from generated documentation, you can specify one or more prefixes here. All keys matching one of the prefixes will be excluded from the documentation. No prefixes are ignored by default.

groups

Allows grouping of configuration keys into separate sections in order to give the generated documentation a more structured form. See example below for more details.

3.3   Examples

TODO: basic with non-default options, ignored prefixes

TODO: injecting generated docs

TODO: grouping (all keys must fall into one of the groups, at lest to defaut one with empty prefix)

TODO: avoid generation of docs in sub-modules by <inherited>false</inherited>

4   Substitutions

According to standard typesafe config behavior, the reference.conf stack must be self-contained. However, to keep the generated configuration documentation environment-agnostic, we don't want it to contain resolved system environment substitutions because that would make the generated documentation specific for the environment where it was generated. Instead, any unresolved substitutions (incl. system environment ones) will be rendered as such.