docs: Added example for figment toml config

[Hecatron]

Hi,
I was having a dig around the issues and discussions for clap for a way to layer a configuration via default values, then a a toml file, then clap using command line arguments (in that order)

• Designing for layered configs #2763

I've discovered one way to do this just using the derive api and figment, so I've added in an example just to show how it works. It does require using serde_default_utils, serde, figment
But I think this might be a common use case.

[epage]

Since figment provides their own example (https://docs.rs/figment/latest/figment/#for-cli-application-authors), what is the thought for the role this fills compared to that one?

[Hecatron]

Since figment provides their own example (https://docs.rs/figment/latest/figment/#for-cli-application-authors), what is the thought for the role this fills compared to that one?

I saw that example initially, but it loads the cli arguments first, then the configuration file second. So any settings in the toml file will override the cli arguments which typically is something you don't want. Normally cli arguments should take precedence over configuration files

To get this to work however there are a couple of less well known things to do
First to add this to avoid clap overwriting options from figment, without this clap will just override the config file with a None if the cli option isn't specified

#[serde(skip_serializing_if = "::std::option::Option::is_none")]

The second is combining that with serde_inline_default to set defaults so that the defaults have a lower priority than the config file

#[serde_inline_default(Some(1))]

[epage]

Note that my question was about what role this fills compared to figment's documentation. Sounds like you have ideas for improving figment's documentation.

[Hecatron]

Ok I could try submitting to see if figment will take the example.
I figured it might be useful here since it's a very common use case is all