I’d like to propose adding an command appendix section to the hugo docs. The command appendix would consist of one section per command. Each section would have:
a table of all configuration settings for that command
setting name
whether it’s a flag or not
shortcut (for flags)
default
help (the setting’s help output, if it exists)
A json file containing all the settings, using their default values.
A toml file containing all the settings, using their default values.
A yaml file containing all the settings, using their default values.
This would be helpful for user’s who look to the documentation about setting information, as opposed to reading the code, which makes Hugo more accessible and user friendly.
The appendix would also provide examples for the settings in the various supported configuration formats. The lack of examples in certain formats can lead to unnecessary friction for new users.
I have started compiling a markdown table of the command. This will address the initial issue, documenting all of Hugo’s configuration settings and their default.
The configuration file versions will be added as they are completed by the Hugo community.
That is a great idea too. I meant to add something like that to my config package.
Your generation idea is excellent too. Dumping out the current config can also be helpful in understanding what is going on with the site, and a pro for knobs, aka settings, vs. hard coding behavior. The rules of behavior for an application become more explicit, instead of being hidden within the code itself.
Anyways, I would probably have Viper output the config to a json object, and then convert it to the other formats there.
One possible issue, for json output, is that the Go standard encoding/json package assumes that all json output will be consumed via the web, so it escapes certain characters for safety. This caused me headaches when I was generating json templates for another application, until I elided that code from the marshal function.
So if you decide to support this in Viper, you might want to look at other ways of writing the JSON version of the file. I have a fork of the standard package that has the escaping in marshal elided. The output can still be escaped using the function call. It also adds some helpers for marshalling JSON to text, which I abuse for debugging complex datastructures in dev.
Also, from what I recall of Viper’s architecture, it also tracks the original state of the setting, and any subsequent modification. It might be useful to be able to output this information, if requested, too.
I briefly contemplated adding some code to Viper to output some of this information as it might be faster to do that and then generate the MD from there than to go through the code. It would also make it easier to maintain the documentation as the appendix could be generated for each release, ensuring that it is consistent with the code. Hmmmm,
I’d welcome any contribution you want to make here. Only change to what you’ve suggested here is I’d use each marshaller directly from a map rather than through the json object.
I’m sure I’ll eventually resign myself to making such a contribution as it seems like the only sane way to do an appendix of commands, settings, and flags and keeping it properly maintained whilst providing thorough examples in the various config formats.
It’d be really useful functionality for a config package to have too.
I’ll move any further discussion on this to Viper for now.
I am finally getting a chance to take a closer look at this.
I’m thinking that the first step would be to add method(s) to viper to return a map[string]interface{} of the settings that it currently has.
Looking at Viper’s Debug() method there are the following datastores:
Config
Key/Value Store
Env
Defaults
Override
Aliases
I see the possibility of two outputs: the default values and the merged values. The default values would consist of the config, defaults, and aliases information. The merged values would consist of the config and aliases values along with the merged values of any env, defaults, and overrides that exist.
I’m not sure how to handle the key/value store here.
I’m also not sure what to do with the workingdir setting. This doesn’t seem pertinant to outputting the configuration settings, but, at the viper level, it might be best to leave it in and have the Hugo output omit this?
I also haven’t worked out handling the command output, but for a configuration setting appendix, it might be that I just grab each command’s output and add that to the documentation.
What was being discussed above was a way of extracting the config to a config file in the various supported format for doc purposes since the documentation doesn’t show examples of the various formats.
This would make it easier for new users to make a new configuration file that suits their needs.
I know I spent some time figuring out how to define some options in a given format from an example given in the docs. I just wanted to lower the friction of creating Hugo configurations.