Add tutorials

docs/resources/config/replace_data_root.py

@@ -0,0 +1,3 @@
+dataset_type = 'CocoDataset'
+data_root = '{{$DATASET:/data/coco/}}'
+dataset = dict(ann_file=data_root + 'train.json')

docs/resources/config/replace_num_classes.py

@@ -0,0 +1 @@
+model = dict(bbox_head=dict(num_classes={{'$NUM_CLASSES:80'}}))

docs/zh_cn/advanced_tutorials/config.md

@@ -15,6 +15,8 @@ wget https://raw.githubusercontent.com/open-mmlab/mmengine/main/docs/resources/c
 wget https://raw.githubusercontent.com/open-mmlab/mmengine/main/docs/resources/config/optimizer_cfg.py
 wget https://raw.githubusercontent.com/open-mmlab/mmengine/main/docs/resources/config/predefined_var.py
 wget https://raw.githubusercontent.com/open-mmlab/mmengine/main/docs/resources/config/refer_base_var.py
+wget https://raw.githubusercontent.com/open-mmlab/mmengine/main/docs/resources/config/replace_data_root.py
+wget https://raw.githubusercontent.com/open-mmlab/mmengine/main/docs/resources/config/replace_num_classes.py
 wget https://raw.githubusercontent.com/open-mmlab/mmengine/main/docs/resources/config/resnet50_delete_key.py
 wget https://raw.githubusercontent.com/open-mmlab/mmengine/main/docs/resources/config/resnet50_lr0.01.py
 wget https://raw.githubusercontent.com/open-mmlab/mmengine/main/docs/resources/config/resnet50_runtime.py
@@ -490,6 +492,76 @@ Config (path: ./example.py): {'model': {'type': 'CustomModel', 'in_channels': [1
 
 :::
 
+### 替换环境变量
+
+当要修改的变量嵌套很深时，我们在命令行中也需要加上很长的前缀来表示这个变量的位置。为了更方便地在命令行中修改配置文件，MMEngine 提供了一套通过环境变量来替换固定片段的方法。
+
+在解析配置文件之前，MMEngine 会搜索所有的 `{{$ENV_VAR:DEF_VAL}}` 字段，并使用字段指定的环境变量来替换这一部分。这里 `ENV_VAR` 为这一字段指定的环境变量，`DEF_VAL` 表示没有设置环境变量时的默认值。
+
+例如，当我们想在命令行中修改数据集的路径时，我们可以在配置文件 `replace_data_root.py` 中这样写：
+
+```python
+dataset_type = 'CocoDataset'
+data_root = '{{$DATASET:/data/coco/}}'
+dataset=dict(ann_file= data_root + 'train.json')
+```
+
+当我们运行 `demo_train.py` 来读取这个配置文件时：
+
+```bash
+python demo_train.py replace_data_root.py
+```
+
+```
+Config (path: replace_data_root.py): {'dataset_type': 'CocoDataset', 'data_root': '/data/coco/', 'dataset': {'ann_file': '/data/coco/train.json'}}
+```
+
+这里因为没有设置环境变量 `DATASET`, 程序直接使用默认值 `/data/coco/` 作为这一部分的值。如果在命令行前设置设置环境变量则会有如下结果：
+
+```bash
+DATASET=/new/dataset/path/ python demo_train.py replace_data_root.py
+```
+
+```
+Config (path: replace_data_root.py): {'dataset_type': 'CocoDataset', 'data_root': '/new/dataset/path/', 'dataset': {'ann_file': '/new/dataset/path/train.json'}}
+```
+
+`data_root` 被替换成了新的路径 `/new/dataset/path/`
+
+```note
+环境变量的替换发生在配置文件解析之前。如果该变量还参与到其他变量的定义时，环境变量替换也会影响到其他变量。在上例中 dataset.ann_file 等于 data_root + 'train.json', 因此当 data_root 被替换时，dataset.ann_file 也会发生变化。而 --cfg-options 是在配置文件解析后去替换特定变量。--cfg-options data_root='/new/dataset/path/' 不会影响到 dataset.ann_file
+```
+
+环境变量也可以用来替换字符串以外的字段，这时可以使用 `{{'$ENV_VAR:DEF_VAL'}}` 或者 `{{"$ENV_VAR:DEF_VAL"}}`。`''` 与 `""` 保证配置文件合乎 python 语法。
+
+例如当我们想替换模型预测的类别数时，可以在配置文件 `replace_num_classes.py` 中这样写：
+
+```
+model=dict(
+    bbox_head=dict(
+        num_classes={{'$NUM_CLASSES:80'}}))
+```
+
+当我们运行 `demo_train.py` 来读取这个配置文件时：
+
+```bash
+python demo_train.py replace_num_classes.py
+```
+
+```
+Config (path: replace_num_classes.py): {'model': {'bbox_head': {'num_classes': 80}}}
+```
+
+当设置 `NUM_CLASSES` 环境变量后：
+
+```bash
+NUM_CLASSES=20 python demo_train.py replace_num_classes.py
+```
+
+```
+Config (path: replace_num_classes.py): {'model': {'bbox_head': {'num_classes': 20}}}
+```
+
 ### 导入自定义 Python 模块
 
 将配置与注册器结合起来使用时，如果我们往注册器中注册了一些自定义的类，就可能会遇到一些问题。因为读取配置文件的时候，这部分代码可能还没有被执行到，所以并未完成注册过程，从而导致构建自定义类的时候报错。