docs: Updating !include documentation for clarity

[badge]

I just had a hell of a time trying to get !include working, and hadn't realised how restrictive the syntax is. This PR clarifies the documentation on includes to prevent future misunderstandings!

[sisp]

Thanks for taking the initiative to improve our docs, @badge! 🙏

Would you mind elaborating a little, what specifically you were struggling with when trying to use !include? What part of the syntax do you consider restrictive and didn't get right immediately? Using the YAML document markers correctly?

I'm asking because your content change – besides some rearranging of text blocks – is this:

+The syntax of a single include is:
+
+```yaml
+---
+!include filename.yml
+---
+```
+
+the `---` on new lines are essential, but you don't need to duplicate them if you have
+two `!include` directives.
+
+!!! hint
+
+    When working with multiple documents, you can use [`exclude`][exclude]
+    to exclude them from the rendered project.

Honestly, I don't find these explanations very intuitive.

1. A single !include directive does not need to be surrounded by ---. Instead, the contents of multiple copier.yml files must be placed in separate YAML documents, which are separate by --- markers. Also, a document start marker (i.e., a YAML file beginning with ---) is optional. For instance, the following copier.yml files are all valid:

   •  !include common.yml

   •  ---
      !include common.yml

   •  !include common.yml
      ---
      custom_question: default answer

   •  ---
      !include common.yml
      ---
      custom_question: default answer

   •  !include common1.yml
      ---
      !include common2.yml

   •  custom_question1: default answer
      ---
      custom_question2: default answer

   • ...

2. +the `---` on new lines are essential, but you don't need to duplicate them if you have
   +two `!include` directives.

   Are you trying to say that the two subsequent --- in

   ---
   !include common1.yml
   --- # <--- duplicates
   --- # <--- duplicates
   !include common2.yml
   ---

   aren't necessary? In fact, they aren't allowed because between those two subsequent --- markers is an empty YAML document which Copier doesn't allow. Also, the document end marker --- at the bottom isn't allowed. We could look into handling empty YAML documents gracefully instead of raising an error. In any case, I don't find the explanation clear and helpful, especially when the concept of YAML documents is known.

3. +!!! hint
   +
   +    When working with multiple documents, you can use [`exclude`][exclude]
   +    to exclude them from the rendered project.

   What do you mean? Unless I'm missing something, I think the existing documentation says all there is to say, i.e. the exclude lists from each document are concatenated. What does "them" in "[...] to exclude them [...]" refer to?

[ssteinerx]

How about just demonstrating and immediately annotating the correct syntax:

!include copier-other.yml
---

Please note that the !include directive MUST be the first line in the file.

The line after the directive must contain only three dashes and a newline character as shown above.

Anything else is invalid and will not work.

[sisp]

Please note that the !include directive MUST be the first line in the file.

The line after the directive must contain only three dashes and a newline character as shown above.

Anything else is invalid and will not work.

That's not correct. The !include directive can appear anywhere in copier.yml as long as it's placed in a separate YAML document. For instance:

• copier.yml;

  q1: hello
  ---
  !include q2.yml

• q2.yml:

  q2: world

[ssteinerx]

Ah, so the first example like this:

!include copier-other.yml
---

actually works because the !include is in the implicit "first document" and the -- marks the end of the first contained document and the beginning of the second.

Can there also be any number of !includes in the file, as long as there's only one per document?

Is this valid?

---  # explicit, optional "start of first document"
!include include1.yml
--- # end first, begin second document
!include include2.yml
--- # end second, begin third document
!include include3.yml
--- # and so forth...

[yajo]

yes

[badge]

@sisp ha, so I tried and clearly failed to open an MR to be helpful, but as you point out the change I proposed was also ambiguous. Perhaps it's better to explain what I understood from the docs as they are.

I assumed I could just do something like this:

use_docker:
    type: bool
    help: Include a Dockerfile?
    default: true

!include copier-docker.yml

use_fortran:
    help: Include build tools for Fortran?
    default: true

What I didn't undestand from the docs was that the --- weren't just to separate out the examples, but were actually necessary for the !include directives to work.

[sisp]

No worries, @badge, it's a good discussion anyway! 👌 So, how about improving clarity by referring more explicitly to YAML documents, perhaps with a link to the official documentation, explaining the need for the document end marker --- and that an !include directive must be placed in a separate YAML document?

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (5f7dc40) 97.46% compared to head (82c2fcc) 97.46%.
Report is 7 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1496   +/-   ##
=======================================
  Coverage   97.46%   97.46%           
=======================================
  Files          48       48           
  Lines        4537     4537           
=======================================
  Hits         4422     4422           
  Misses        115      115           

Flag	Coverage Δ
unittests	97.46% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.