keyword documentation for config.yaml

[Jasha10]

In yaml files, there are several keywords that hydra treats specially. It would be nice to have a page in the Hydra reference manual listing all of these keywords in once place.

Here are the keywords I'm aware of, as well as links to their primary documentation:

• _self_: https://hydra.cc/docs/1.2/advanced/defaults_list#composition-order
• _here_: https://hydra.cc/docs/1.2/advanced/overriding_packages#default-list-package-keywords
• _group_: https://hydra.cc/docs/1.2/advanced/overriding_packages#default-list-package-keywords
• _global_: https://hydra.cc/docs/1.2/advanced/overriding_packages#default-list-package-keywords
• # @package directive: https://hydra.cc/docs/1.2/advanced/overriding_packages/#overriding-the-package-via-the-package-directive
• override: https://hydra.cc/docs/1.2/advanced/defaults_list#introduction, https://hydra.cc/docs/1.2/patterns/configuring_experiments#example
• optional: https://hydra.cc/docs/1.2/advanced/defaults_list#introduction, https://hydra.cc/docs/1.2/patterns/specializing_config#optional
• null: https://hydra.cc/docs/1.2/advanced/defaults_list#introduction (this is just plain yaml, but it is mentioned together with override and optional)

For use with instantiate:

• _target_: https://hydra.cc/docs/1.2/advanced/instantiate_objects/overview
• _args_: https://hydra.cc/docs/1.2/advanced/instantiate_objects/overview
• _recursive_: https://hydra.cc/docs/1.2/advanced/instantiate_objects/overview
• _partial_: https://hydra.cc/docs/1.2/advanced/instantiate_objects/overview
• _convert_: https://hydra.cc/docs/1.2/advanced/instantiate_objects/overview

[omry]

Those keywords are from many different levels of the stack.

• null -> yaml
• @package -> Config loading
• optional, override, _self_, _here_ -> Defaults List
• _target_ -> instantiation.

I am not sure where such a catchall page would fit or if it's worth replicating the information in the docs you linked to to it.

[Jasha10]

where such a catchall page would fit

Here's what I was thinking:

• the page could be titled something like "YAML Keyword Reference", included as part of the "Reference Manual" section of the docs.
• Each keyword gets a 1 or 2 sentence description (high-level), as well as a link pointing to the primary documentation that appears elsewhere in the docs. I agree that the information from the other parts should not be replicated...
• I guess we would skip null since it's not part of Hydra.

Anyway, organizing this info was helpful to me in trying to understand the features of Hydra, especially for packages and default lists. Even if we don't add a page to the docs, maybe the issue above can provide reference for future users.

[omry]

the page could be titled something like "YAML Keyword Reference", included as part of the "Reference Manual" section of the docs.

This is not just YAML, most of these will work in the defaults list of Structured Configs as well. The only thing that is yaml specific is the package header, and even that got an equivalent when using the ConfigStore.

[jieru-hu]

I think such a page would be really helpful! Have such a page will also help reinforce the idea that ConfigStore and YAML two different ways of providing configs to Hydra for composition.