Tools for automatic documentation generation from typesafe config configurations.
Contents
- 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.