Search code examples
fb-hydra

Documentation of Hydra Config

Hydra provides a way to dynamically create a hierarchical configuration by composition and override it through config files and the command line, leveraging OmegaConf. I look for a recommended way to document the parameters but I could not find (a documented) one. What are best practices for that? Coming from argparse, I like the way of documenting the parameter inline, i.e. close to the code.

Solution

  • Excellent question! The answer is: parameter-by-parameter documentation is not yet implemented (as of Hydra v1.1, OmegaConf v2.1).

    The future plans are:

    • in OmegaConf, expose an API allowing users to attach documentation (and other metadata) to each field of a structured config. See this open OmegaConf issue.
    • Once the above is complete, implement a Hydra feature allowing a parameter-specific help messages to be printed based on the parameter's metadata. See this open Hydra issue.

    For now, the best we can do is to customize the general application help message (i.e. the --help command line flag).