docs(README): 更新文档并添加高级用法示例

- 更新基本示例 1 的说明
- 添加高级用法部分，介绍 pyyaml-include 的使用方法
- 更新代码示例和解释

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: check-case-conflict
       - id: check-added-large-files
@@ -17,19 +17,19 @@ repos:
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: v0.5.1
+    rev: v0.8.2
     hooks:
       - id: ruff
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: "v1.10.1"
+    rev: "v1.13.0"
     hooks:
       - id: mypy
         args: [--ignore-missing-imports, --config-file, .mypy.ini]
         additional_dependencies: [types-PyYAML]
 
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: "0.28.6"
+    rev: "0.30.0"
     hooks:
       - id: check-github-workflows
       - id: check-readthedocs

README.md

@@ -14,7 +14,7 @@ instead of whole YAML string as a template.
 
 ## Usage
 
-### Example 1
+### Basic Example 1
 
 1. Add `Jinja2` template constructor for tag `"!j2"`
 
@@ -54,7 +54,11 @@ We'll get:
 {"array": [{"sub0": 1}, {"sub1": 2}, {"sub2": 3}]}
 ```
 
-### Example 2
+## Advanced Usage
+
+### Include files
+
+#### Jinja2's include filter function
 
 We have such YAML files:
 
@@ -118,9 +122,70 @@ We'll get:
          "2.1": {"2.1.1": "three", "2.1.2": "four"}}}
 ```
 
-> **NOTE:**
->
-> Since [Jinja2][]'s [`include`](https://jinja.palletsprojects.com/en/3.0.x/templates/#include) and [`indent`](https://jinja.palletsprojects.com/en/3.0.x/templates/#jinja-filters.indent) do not work very nice with indention languages like Python or YAML, it's not advised to use the feature in a complex case.
+> ℹ️ **Note:** \
+> Since [jinja2][]'s [`include`](https://jinja.palletsprojects.com/en/3.0.x/templates/#include) and [`indent`](https://jinja.palletsprojects.com/en/3.0.x/templates/#jinja-filters.indent) do not work such nice with indention-sensitive languages like Python or YAML, it is not advised to use these features in complex cases.
+
+#### pyyaml-include
+
+[pyyaml-include][] provides a [pyyaml][] extension for including other YAML files.
+Sometimes we use this extension instead of Jinja2's `include`/`indent` to help maintain the indentation of the YAML file.
+
+1. install [pyyaml-include][]:
+
+    ```bash
+    pip install pyyaml-include
+    ```
+
+1. add both [pyyaml-include][] and `jinjyaml`'s constructor:
+
+    ```python
+    import yaml
+    import jinjyaml as jy
+    import pyyaml_include
+
+    yaml.add_constructor("!j2", jy.Constructor)
+    yaml.add_constructor("!inc", pyyaml_include.Constructor(base_dir="path_to_you_dir"))
+    ```
+
+1. Assume that we have YAML files same to previous example, the `main.yml` can be modified as below:
+
+    ```yaml
+    foo: !j2 |
+      {% for i in range(n) %}
+      - !inc sub-{{loop.index}}.yml
+      {% endfor %}
+    ```
+
+1. include and load other YAML files:
+
+    Assume that we have YAML files same to previous example:
+
+    ```python
+    with open("main.yml") as fp:
+        doc = yaml.safe_load(fp)
+
+    obj = jy.extract(doc, env)
+    pprint(obj)
+    ```
+
+Then we'll get:
+
+```json
+{
+  "foo": [
+    {"1.1": "one", "1.2": "two" },
+    {"2.1": {"2.1.1": "three", "2.1.2": "four"}}
+  ]
+}
+```
+
+In the situation, it's no necessary to use `jinja2.Environment` and `jinja2.FileSystemLoader` to render the template,
+and also not necessary to use `filter indent` in the template.
+Because [pyyaml-include] has parsed the file to object already.
+
+> ❇️ **Conclusions:** \
+> We can use [jinja2][]'s `include` and `indent` to include other YAML files **literally**, or to use [pyyaml-include][] to include other YAML files **as already-parsed objects**.
 
 [jinja2]: https://jinja.palletsprojects.com/ "Jinja is a fast, expressive, extensible templating engine."
 [pyyaml]: https://pyyaml.org/ "PyYAML is a full-featured YAML framework for the Python programming language."
+[pyyaml-include]: https://github.com/tanbro/jinjyaml "An extending constructor of PyYAML: include other YAML files into current YAML document."