Example config generation
=========================

CONFspirator supports generated config files from the built
config tree. These will populate all the fields, and if a
default value is supplied will put that in place.

To use this functionality you must supply your root config group,
and call the function with a file location. CONFspirator does not
supply any CLI support for this, so you will want to build a command
into your application or project to import your root config group,
and call the generation function.

Assuming the config group as shown in the getting started page::

    # ./my_app/config/root.py
    from confspirator import groups, fields

    root_group = groups.ConfigGroup(
        "my_app", description="The root config group.")
    root_group.register_child_config(
        fields.StrConfig(
            "top_level_config",
            help_text="Some top level config on the root group.",
            default="some_default",
        )
    )

    # ./my_app/config/sub_section.py
    from confspirator import groups, fields
    from my_app.config import root

    sub_group = groups.ConfigGroup(
        "sub_section", description="A sub group under the root group.")
    sub_group.register_child_config(
        fields.BoolConfig(
            "bool_value",
            help_text="some boolean flag value",
            default=True,
        )
    )

    root.root_group.register_child_config(sub_group)

You would call the generation logic as follows::

    # ./my_app/commands.py

    import confspirator
    from my_app.config import root


    def create_config():
        confspirator.create_example_config(
            root.root_group, "conf.yaml")

This would produce a yaml config example that looks like the following::

    # String - Some top level config on the root group.
    top_level_config: some_default
    # A sub group under the root group.
    sub_section:
      # Boolean - some boolean flag value
      bool_value: true

Alternatively if you wanted ``toml`` instead, you can simply change the
file extension and the exporter will pick that up. Or if you want to use
an extension other than ``yaml`` or ``toml`` you can explicitly set
``output_format`` to either ``yaml`` or ``toml``, and the file extension
will be ignored::

    confspirator.create_example_config(
        root.root_group, "my_app.conf", output_format="toml")

In any case, if by extension or explicit output format ``toml`` is set,
your generated example config will look as follows::

    [my_app]
    # String - Some top level config on the root group.
    top_level_config = "some_default"

    # A sub group under the root group.
    [my_app.sub_section]
      # Boolean - some boolean flag value
      bool_value = true

For complicated nested configs yaml tends to be easier to deal with,
but for people with a preference for ``ini`` style configs toml does
provide a good option that still allows nesting.