From d9f6330ad9a5f0b1c49cac957a747e71981f5d5b Mon Sep 17 00:00:00 2001 From: Matthew Badger Date: Fri, 2 Feb 2024 11:14:53 +0000 Subject: [PATCH 1/2] Updating !include documentation for clarity --- docs/configuring.md | 51 +++++++++++++++++++++++++++++++++------------ 1 file changed, 38 insertions(+), 13 deletions(-) diff --git a/docs/configuring.md b/docs/configuring.md index 3ac8b3d12..bd47f993d 100644 --- a/docs/configuring.md +++ b/docs/configuring.md @@ -383,19 +383,7 @@ cannot use Jinja templating in your answers. The `copier.yml` file supports multiple documents as well as using the `!include` tag to include settings and questions from other YAML files. This allows you to split up a larger `copier.yml` and enables you to reuse common partial sections from your -templates. When multiple documents are used, care has to be taken with questions and -settings that are defined in more than one document: - -- A question with the same name overwrites definitions from an earlier document. -- Settings given in multiple documents for `exclude`, `skip_if_exists`, - `jinja_extensions` and `secret_questions` are concatenated. -- Other settings (such as `tasks` or `migrations`) overwrite previous definitions for - these settings. - -!!! hint - - You can use [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) - to sanely include shared code into templates. +templates. !!! example @@ -432,6 +420,43 @@ settings that are defined in more than one document: - "pyproject.toml" ``` +The structure of includes is quite restrictive: they must come at the top of the yaml +file, and end with `---` on a new line. + +!!! example + + This is an _invalid_ copier.yml file: + + ```yaml title="copier-invalid.yml" + version: + type: str + help: What is the version of your Python project? + + !include copier-other.yml + ``` + + This is invalid twice over: we haven't put the `!include` directive at the top + of the file, and we haven't included `---` in a new line after it. + +!!! hint + + When working with multiple documents, you can use [`exclude`][exclude] + to exclude them from the rendered project. + +When multiple documents are used, care has to be taken with questions and +settings that are defined in more than one document: + +- A question with the same name overwrites definitions from an earlier document. +- Settings given in multiple documents for `exclude`, `skip_if_exists`, + `jinja_extensions` and `secret_questions` are concatenated. +- Other settings (such as `tasks` or `migrations`) overwrite previous definitions for + these settings. + +!!! hint + + You can use [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) + to sanely include shared code into templates. + ## Conditional files and directories You can take advantage of the ability to template file and directory names to make them From 82c2fcc936d1204b0f6b8afe77f907e21f79a090 Mon Sep 17 00:00:00 2001 From: Matthew Badger Date: Fri, 2 Feb 2024 11:31:56 +0000 Subject: [PATCH 2/2] Correcting explanation, giving minimal example --- docs/configuring.md | 23 ++++++++--------------- 1 file changed, 8 insertions(+), 15 deletions(-) diff --git a/docs/configuring.md b/docs/configuring.md index bd47f993d..cfe0dbd1b 100644 --- a/docs/configuring.md +++ b/docs/configuring.md @@ -420,23 +420,16 @@ templates. - "pyproject.toml" ``` -The structure of includes is quite restrictive: they must come at the top of the yaml -file, and end with `---` on a new line. +The syntax of a single include is: -!!! example - - This is an _invalid_ copier.yml file: - - ```yaml title="copier-invalid.yml" - version: - type: str - help: What is the version of your Python project? - - !include copier-other.yml - ``` +```yaml +--- +!include filename.yml +--- +``` - This is invalid twice over: we haven't put the `!include` directive at the top - of the file, and we haven't included `---` in a new line after it. +the `---` on new lines are essential, but you don't need to duplicate them if you have +two `!include` directives. !!! hint