guide: document matrix in dvc.yaml

[skshetry]

fixes #4741
upstream PR: iterative/dvc#9725
available since https://github.com/iterative/dvc/releases/3.12.0

[github-actions]

Link Check Report

There were no links to check!

[dberenbaum]

What do you mean by your imported file? Should we also mention that you can reference params files? It would be great to have a more complete example here (show the vars section and/or params.yaml file).

[skshetry]

With imported, I meant vars loaded from files. But yes, it is confusing. I'll just get rid of it, and replace with an example of vars from params.yaml. Others should be left to the readers/users I think.

[dberenbaum]

Thanks @skshetry! Nice examples.

Let's at least mention in foreach that matrix now provides a more powerful way to define multiple stages in a single entry. I think we should go even further and say that foreach may be deprecated in future versions, so we recommend using matrix instead.

[skshetry]

Let's at least mention in foreach that matrix now provides a more powerful way to define multiple stages in a single entry. I think we should go even further and say that foreach may be deprecated in future versions, so we recommend using matrix instead.

I'll just recommend for now. Let's get some feedback first. :)

[daavoo]

Definitely not a blocker for this P.R. but #3670 feels now even more important to address.
Too much important info in a place "too hidden"

[dberenbaum]

Can we change to a code block like this just to save space? The bullet points take up a lot space.

$ dvc stage list
train@cnn-feature1  Outputs cnn.pkl
train@cnn-feature2  Outputs cnn.pkl
train@cnn-feature3  Outputs cnn.pkl
train@xgb-feature1  Outputs xgb.pkl
train@xgb-feature2  Outputs xgb.pkl
train@xgb-feature3  Outputs xgb.pkl

[dberenbaum]

Pushed the change myself since I don't know how to add a code block in a suggestion, and I'm assuming this isn't a controversial change.

[dberenbaum]

Thanks @skshetry!

As a follow-up (unless you want to include in this PR), let's also add an example showing how it works with dict unpacking.

[skshetry]

Definitely not a blocker for this P.R. but #3670 feels now even more important to address.
Too much important info in a place "too hidden"

As a follow-up (unless you want to include in this PR), let's also add an example showing how it works with dict unpacking.

I think there are three parts here on how we should decouple:

1. Expressions (whatever inside ${}), and dict unpacking.
2. Templating, foreach and matrix
3. Stage/Output schema

To me, it feels like matrix example belongs in dict unpacking rather than matrix (which is hidden right now).

[dberenbaum]

@skshetry Why don't we discuss in #3670?

BTW, I don't understand what you mean by this:

matrix (which is hidden right now).