Provide a tool to generate configuration documentation
Gitaly and Praefect have various distributions such as source, charts and Omnibus. Every time configuration is changed, we should update the documentation in the various distributions. This becomes quickly quite a maintenance burden. It's also easy to forget and our documentation currently doesn't cover all of the available configuration.
We should provide a tool that outputs Gitaly's configuration in structured format that can be used to generate documentation. This tool could then be used by the various distributions to generate documentation reference:
- For source installs, we can generate the
praefect/gitaly.example.toml
in our repository with the tool. - For Omnibus, we could generate a complete reference in https://docs.gitlab.com/ee/administration/gitaly/reference.html with the tool.
- For Charts, we could also generate a similar reference.
The tool itself should not generate the documentation but only provide a way to get the structure out along with the documentation. The various projects that need the documentation could then call the tool, parse the output and use it to generate the documentation as they need.
The distributions currently have differing config keys and structures which makes this more difficult but after #4467 (closed), they'd all have the same structure.