Tools for automatic documentation generation from typesafe config configurations.
- 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
<dependency>
<groupId>io.github.okvee</groupId>
<artifactId>tscfg-docgen-core</artifactId>
<version>x.y.z</version>
</dependency>
<plugin>
<groupId>io.github.okvee</groupId>
<artifactId>tscfg-docgen-maven-plugin</artifactId>
<version>x.y.z</version>
</plugin>
<plugin>
...
<executions>
<executions>
<id>gen-docs</id> (1)
<phase>process-resources</phase> (2)
<goals>
<goal>generate-docs</goal> (3)
</goals>
</executions>
</executions>
</plugin>
- A unique ID of this execution
- Phase in which the execution should take place (by default, this is
site
) - Goal to be executed (currently,
generate-docs
is the only supported goal)
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 matchesreference.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 tomarkdown-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
andinjectionEndPlaceholder
options. Defaults tofalse
.- injectionStartPlaceholder
In case
injectGeneratedDocs
istrue
, 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
istrue
, 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.
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>
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.