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!

[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! :ok_hand: 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[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

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.

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.