Add inheritance and composition section in user docs

[francesco086]

Contributes to #934

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.03%. Comparing base (aad1f7d) to head (569a267).
Report is 5 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #2165   +/-   ##
=======================================
  Coverage   98.03%   98.03%           
=======================================
  Files          55       55           
  Lines        6005     6005           
=======================================
  Hits         5887     5887           
  Misses        118      118           

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

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.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sisp]

Thanks for volunteering to write documentation on this complex topic, @francesco086! 🙏 I have a few suggestions, curious what you think.

Regarding solutions: Meta-templates is another one, although I don't know how relevant it actually is in practice.

[sisp]

How about renaming the file to reusing.md (intentionally as a gerund for consistency with some other files like configuring.md) to keep the URL path concise and also less specific to a particular reuse approach?

[francesco086]

My feeling is that reusing is too generic, and it is especially confusing in the context of copier. The first thing that would come to my mind is "Of course! I have some code that I want to re-use by creating a template! Let's see how".

What about composing, composing_templates, or inheriting_and_composing_templates (too long perhaps)? Alternatively, reusing_templates may be explicit enough.

I leave the final decision to you / the maintainers, just let me know what do you think is best and I will apply 😄

[sisp]

For consistency with the renamed file:

Suggested change

	# Template Inheritance and Composition
	# Template Reuse

[sisp]

Perhaps this is more concise?

Suggested change

	## What is Inheritance, what is Composition?
	## Inheritance vs. Composition

[francesco086]

True, but it miss the key point that this section is "What are we talking about", and not only comparing them.

In my head this section was the WHAT. Then there is the WHY, and finally HOW (solutions).

[sisp]

I think it's mostly about extensions, not so much variations – perhaps a matter of definition. Variations – in my mind – can often be addressed by conditional questions and conditional rendering in the same template. WDYT?

Suggested change

	overriding specific parts in the child template. This is useful for creating variations
	overriding specific parts in the child template. This is useful for creating extensions

[francesco086]

I agree with what is in your head, but this is exactly the reason why I think inheritance is useful, to avoid the ugly if/else.

By the way this is exactly what I did in my example, where we did not agree that it was inheritance.
I would like to mention that if you look carefully at the example you may notice that I did start with if/else (this is the key question), but it became a horror to maintain the template. Very complex, very hard to read, and very slow tests. This is why on the next flavor I had to add, I decided for this "inheritance" approach, which worked decently, except for the drawbacks you already clarified very well, especially when it comes to copier update.

But you made a good point, in my opinion we should mention both. An alternative term for "variation" is "flavor" by the way.

Do you think we can agree to write "This is useful for creating extensions and variations"?

[sisp]

Do you have an approach like yours using tasks that run copier copy in mind? I've mostly thought of "composition" along the lines of https://copier.readthedocs.io/en/stable/configuring/#applying-multiple-templates-to-the-same-subproject. There, template composition means generating output from multiple templates in the same target directory, but there is no new template that is a composition of other templates.

[francesco086]

I think it is up to discussion!

The solution you mentioned is what I consider the "manual" solution. But of course leaves the problem of "what if it is very common to compose always the same 3 templates" and want to make it more convenient for a user to get the 3 together and don't need to manually check that they have compatible versions?

But yes, I think that using tasks could be a way, of course with the drawbacks already mentioned.

[francesco086]

To avoid forgetting about it, I also added this to the solutions

[sisp]

Suggested change

	### Git submodules + jinja template inheritance
	### Git submodules + Jinja template inheritance

🤓

[francesco086]

🥷

[sisp]

See above:

Suggested change

	- Template Inheritance and Compostion: "inheritance_and_composition.md"
	- Reusing templates: "reusing.md"

[sisp]

I anticipate that a proper solution might require Copier to support it natively. At least for the fork-like workflow, I think that specified template versions in parent template migrations need to be mapped to child template versions – at the very least. But it's too early to make a definitive statement.

[francesco086]

I see that coming too! But I think @yajo had some very valid points. So, let's see where do we end up to, and let's try to keep what he said in mind.

[francesco086]

Reading carefully what he wrote once again, it seems to me that everything reduces to the UNIX philosophy of "do one thing well", or am I wrong?

I filled the WHY section

[francesco086]

Regarding solutions: Meta-templates is another one, although I don't know how relevant it actually is in practice.

Right! I think it is not really a solution for inheritance and composition tbh, but I added it to the list, and we will discuss it at due time