Merge pull request #294 from gridai/doc-398-more-thorough-config-yaml-documentation

Config file schema and defaults

Author: oojo12

docs/features/runs/17_yaml-configs/2_yaml-api.md

@@ -10,7 +10,7 @@ The following YML file contains a commented version of every YML key. You need t
 Use either [cluster context](../../../platform/2_Custom%20Cloud%20Credentials/5_grid-cluster-context.md) or make sure to place your cluster ID in the `cluster` field, replacing the **XXXXXX** placeholder.
 :::
 
-```text
+<!-- ```text
 # Main compute configuration.
 compute:
 
@@ -44,13 +44,69 @@ hyper_params:
     # your params here
     --foo: 1
     -bar: 2
-```
+``` -->
 
-:::note
-Flags in grid YML files have a 1-to-1 mapping with `grid run` flags
-:::
 
-In addition to the parameters above, you can also run arbitrary commands on different stages of you training operation.
+Config can be used to specify arguments that will be used to run experiments. 
+Apart from parametrization config allows to define custom `actions` executed in given moments of the experitment lifecycle, and pass environment variables.
+You don't have to define more parameters than you actually want to override, missing ones from config we have the default CLI values.
+To check the defaults please refer to the CLI docs [here](../../cli.md).
+
+
+```text
+# Main compute configuration. Defines parameters for `grid run` command. 
+compute:
+
+  # For BYOC users, we can specify directly which cluster to run experiments on.
+  provider:
+    cluster: prod-2                         # [str] --cluster
+
+  # Train section defines the training environment each experiement eg. instance type, datastore access, custom actions.
+  train:
+    framework: lightning                    # [enum] --framework
+    environment:
+      MY_ENVIRONMENT_VARIABLE: "example"    # Pass in environment variables
+    dependency_file_info:
+      path: null                            # [str] --dependency_file
+    instance: m5a.large                     # [enum] --instance_type
+    use_spot: False                         # [str] --use_spot
+
+# We should ideally remove those are we hope to depricate gpus/cpus
+#    cpus: int 1                            # --cpus - cannot be more than available in the `instance`
+#    gpus: int 0                            # --gpus - cannot be more than available in the `instance`
+    storage_gb: 100                         # [int] --memory [should be greater than 100Gb]
+    localdir: False                         # [bool] --localdir
+    dockerfile: null                        # [str] --dockerfile
+    auto_resume: bool                       # [bool] --auto_resume (flag)
+    datastore_name: null                    # [str] --datastore_name
+    datastore_version: null                 # [int] --datastore_version
+    datastore_mount_dir: null               # [str] by default mounts to /datastores/{datastore_name}  --datastore_mount_dir
+    actions:                                # Pass list of commands to be executed at given moment.
+      on_build: null                        # List[str]
+      on_build_start: null
+      on_build_end: null
+      on_experiment_end: null
+      on_experiment_start: null
+    scratch:
+      size_gb: 100                          # [int] --scratch_size default 100 int
+      mount_path: /tmp/scratch              # [str] --scratch_mount_path default
+
+# This section defines the hyperparameters settings. 
+# We currently have 3 strategies: grid_search, random_search and none.
+# strategy_options are only for the random_search strategy.
+hyper_params:
+  settings:
+    strategy: grid_search                   # [enum] One of `['grid_search', 'random_search', 'none']`
+    strategy_options:                       # For 'random_search' we must at least define num_trials 
+      num_trials: 1                         # [int] we must specify the num_trials (via CLI or config) if we use random_search strategy (--num_trials)
+      seed: 0                               # [int] --seed
+  
+  # Additional script parameters appended as "{key} {value}"
+  params: [dict[str, str]]                  # Dict of key: value entries appended to as script parameters
+    --foo: 1                                # [str: str]
+    -bar: something
+```
+
 
 ## Creating Runs With a Config File