Change of approach:

• What is the minimal conf.yaml that works?
• How can we help the user configure things?

I think we can do something like

nikola config OPT_NAME

that will add the option to conf.yaml if it exists in our option schema (to be created)

We can then add a nikola config update that will do the config updates we now have as fallbacks in code inside nikola

I think this can work nicely.

This is terrible for discoverability. By editing conf.py right now, you can find all the settings in one place. In the new model, how would you learn about settings? From the website?

On one hand yes, conf.py makes it possible to discover things by reading a thousand lines of code.

On the other hand, we have had complaints that conf.py is horribly confusing, and we have no way to actually do things like adding new options to conf.py once we add them in master.

So, maybe a nikola config --add-all that adds all options with default values?

Makes sense. We would probably need a web resource for settings, perhaps with categorization?

Something like that.

I think plugins should be able to introduce their own options, too.

Of course the real work is:

1. Figure out how to describe a setting properly
2. Make the commands to manage settings
3. Port all settings to the new framework

The UX for WeeChat's key command comes to mind here: https://weechat.org/files/doc/stable/weechat_user.en.html#command_weechat_key

@polyzen nice!

Isn't YAML better for discovery, because you can add commented out descriptions for new keys to an existing YAML when Nikola is updated? Doing this with conf.py is more difficult. Granted the current space for round-trip YAML parsing in Python is pretty abysmal (simply put, there is currently no existing 100% round tripping YAML parser). You might also consider some of the downsides of YAML as a language. It has a lot of gotchas related to its automatic type inference.

TOML is another consideration as it's (more) configuration-oriented.

@asmeurer ruamel does roundtrip comments which is the part I am most interested in

@polyzen TOML doesn't really roundtrip comments, last I checked.

┐('～`；)┌ https://github.com/LeopoldArkham/Molten

@polyzen

TOML sucks because of it's table syntax.
— @ralsina in 2016

I’ll also add the lack of null values to this.

I had totally forgot how awful TOML tables were

There are things that I prefer about YAML and there are things that I prefer about TOML. In a context like this where we are working with large config files, with many options, I lean towards TOML because I feel that nested structures are more legible from a user perspective.

TOML Kit can round trip TOML and allows for adding / manipulating comments.

Caveat: I am pretty ok with conf.py so I don't have much of a horse in this race.

@gwax TOML's support for table-like data is horrible.

Playground is closed forever.