Update docs [ci skip]

website/docs/usage/training.md

@@ -114,8 +114,9 @@ Some of the main advantages and features of spaCy's training config are:
   passed into them. You can also register your own functions to define
   [custom architectures](#custom-models), reference them in your config and
   tweak their parameters.
-- **Interpolation.** If you have hyperparameters used by multiple components,
+- **Interpolation.** If you have hyperparameters or other settings used by
-  define them once and reference them as variables.
+  multiple components, define them once and reference them as
+  [variables](#config-interpolation).
 - **Reproducibility with no hidden defaults.** The config file is the "single
   source of truth" and includes all settings. <!-- TODO: explain this better -->
 - **Automated checks and validation.** When you load a config, spaCy checks if
@@ -307,7 +308,66 @@ compound = 1.001
 
 ### Using variable interpolation {#config-interpolation}
 
-<!-- TODO: describe and come up with good example showing both values and sections -->
+Another very useful feature of the config system is that it supports variable
+interpolation for both **values and sections**. This means that you only need to
+define a setting once and can reference it across your config using the
+`${section:value}` or `${section.block}` syntax. In this example, the value of
+`seed` is reused within the `[training]` block, and the whole block of
+`[training.optimizer]` is reused in `[pretraining]` and will become
+`pretraining.optimizer`.
+
+> #### Note on syntax
+>
+> There are two different ways to format your variables, depending on whether
+> you want to reference a single value or a block. Values are specified after a
+> `:`, while blocks are specified with a `.`:
+>
+> 1. `${section:value}`, `${section.subsection:value}`
+> 2. `${section.block}`, `${section.subsection.block}`
+
+```ini
+### config.cfg (excerpt) {highlight="5,18"}
+[system]
+seed = 0
+
+[training]
+seed = ${system:seed}
+
+[training.optimizer]
+@optimizers = "Adam.v1"
+beta1 = 0.9
+beta2 = 0.999
+L2_is_weight_decay = true
+L2 = 0.01
+grad_clip = 1.0
+use_averages = false
+eps = 1e-8
+
+[pretraining]
+optimizer = ${training.optimizer}
+```
+
+You can also use variables inside strings. In that case, it works just like
+f-strings in Python. If the value of a variable is not a string, it's converted
+to a string.
+
+```ini
+[paths]
+version = 5
+root = "/Users/you/data"
+train = "${paths:root}/train_${paths:version}.spacy"
+# Result: /Users/you/data/train_5.spacy
+```
+
+<Infobox title="Tip: Override variables on the CLI" emoji="💡">
+
+If you need to change certain values between training runs, you can define them
+once, reference them as variables and then [override](#config-overrides) them on
+the CLI. For example, `--paths.root /other/root` will change the value of `root`
+in the block `[paths]` and the change will be reflected across all other values
+that reference this variable.
+
+</Infobox>
 
 ### Model architectures {#model-architectures}
 

website/src/styles/layout.sass

@@ -373,7 +373,7 @@ body [id]:target
     margin-right: -1.5em
     margin-left: -1.5em
     padding-right: 1.5em
-    padding-left: 1.1em
+    padding-left: 1.25em
 
     &:empty:before
         // Fix issue where empty lines would disappear