Generate config.toml.example from config.go programmatically

Problem

The current config.toml.example file is manually maintained, which creates several issues:

1. When new configuration options are added to config.go, the example file can easily become outdated
2. Comments and documentation in the example file may not accurately reflect the actual structure and validation rules defined in the code
3. Default values are not clearly indicated in the example file, making it difficult for users to understand what happens if they omit a setting
4. Manual maintenance requires extra effort and introduces the risk of human error

A similar situation exists with config.praefect.toml.example, which suggests this is a recurring pattern that should be addressed.

Proposal

Create a tool to automatically generate config.toml.example directly from the internal/gitaly/config/config.go file. This would:

1. Add a new struct tag to the configuration fields to indicate whether they should be part of the minimal example configuration
2. Extract comments from the Go code to document the configuration options
3. Clearly indicate default values for each configuration option
4. Present all configuration options as commented by default except for minimal required settings

Implementation approach

1. Add a new struct tag to config.go fields, something like example:"minimal" to indicate fields that should be uncommented in the minimal example configuration

2. Create a new Go command in cmd/ directory that:

   • Parses the config.go file using Go's AST package
   • Extracts struct fields, their types, associated comments, and the new example tags
   • Clearly indicates default values in the generated documentation
   • Uses github.com/pelletier/go-toml/v2 to generate properly formatted TOML output

3. Add the generation step to the build process to ensure the example is always up-to-date

Benefits

• Documentation stays in sync with code implementation
• Default values are clearly documented for all configuration options
• Reduces risk of configuration errors for users due to outdated example files
• Consistent documentation style for all configuration options
• Saves developer time by eliminating manual updates to example files