It would be great if we could leverage the definition of the configuration file to also generate documentation for it, to help application end-users write configuration files.
Right now, if we want to provide documentation for configuration files, we have to maintain it separately, or point end-users at the .d file, neither of which is ideal.
It seems to be one of the stated project goals - in the README:
How do I document it ?
however, I don't think we have anything for this right now.
Ideally, the output should be a generic machine-readable format that can then be converted to other formats shippable as end-user-consumable documentation, i.e. Markdown / HTML / man page / JSON schema (for editor integration).
I haven't looked too deeply into it, but it's possible that we only really need to add generation of a JSON schema, with everything else derivable from that using existing tooling.
It would be great if we could leverage the definition of the configuration file to also generate documentation for it, to help application end-users write configuration files.
Right now, if we want to provide documentation for configuration files, we have to maintain it separately, or point end-users at the
.dfile, neither of which is ideal.It seems to be one of the stated project goals - in the README:
however, I don't think we have anything for this right now.
Ideally, the output should be a generic machine-readable format that can then be converted to other formats shippable as end-user-consumable documentation, i.e. Markdown / HTML / man page / JSON schema (for editor integration).
I haven't looked too deeply into it, but it's possible that we only really need to add generation of a JSON schema, with everything else derivable from that using existing tooling.