doc: add doc about foreach target

[skshetry]

Syncing with iterative/dvc#8352. I am skipping repro and exp run because they are well discussed in the Options sections, and we wanted to avoid describing too much and took the example-based approach in the docs.

See #1983. The support for foreach group name in the target was extended in iterative/dvc#8210.

[github-actions]

5662ee8

Link Check Report

There were no links to check!

[daavoo]

I am not sure if people would know what foreach-group means.

It is not used in https://dvc.org/doc/user-guide/project-structure/dvcyaml-files#foreach-stages which are the only existing docs for foreach

[jorgeorpinel]

Agreed. I don't think this change is needed TBH: foreach groups ultimately become stages so it's covered with "or stage names". No need to be that super explicit about every possible syntax in the help output, especially for such an advanced feature (not that used from what I understand).

• Explaining that you can target them in the foreach docs linked above should be enough IMO.

[dberenbaum]

Thanks, @skshetry!

I am skipping repro and exp run because they are well discussed in the Options sections, and we wanted to avoid describing too much and took the example-based approach in the docs.

Should we add a foreach example in the options section then? I don't see foreach mentioned anywhere. Also, same with stage list.

[jorgeorpinel]

Also, the syntax here is unclear. Probably revert to a comma if we keep this? Maybe

Suggested change

	targets Limit command scope to these tracked files/directories,
	.dvc files and stage or foreach-group names.
	targets Limit command scope to these tracked files/directories,
	.dvc files, stage (or foreach) names.

Rel. iterative/dvc#8352 (review)

[jorgeorpinel]

add a foreach example in the options section then?

Adding that to targets (under https://dvc.org/doc/command-reference/repro#options) as well as possibly a stand-alone example could help indeed since this topic is only covered in the dvc.yaml ref atm and we want cmd refs to be as comprehensive/ self-contained as possible.

p.s. note that the targets arg in the Options section doesn't have a 🔗 anchor like all the options, probably because it doesn't correspond to an actual flag/option arg -- if that's a problem we can check what to do about it with the websites team. Cheers

[dberenbaum]

Closed in favor of #4010