cmd ref: review `root` ref to be aligned with other commands

See https://dvc.org/doc/commands-reference/root.

i.

• The layout of this command reference is outdated.

• It should be the same as for the cache for example.

ii.

• Description should include a better motivation for this command - mostly ease of generating stage files no matter where you run the dvc run.

• Examples should be actionable and meaningful. It’s should be easy to run commands to see the results.

iii.

• ~~A new example about shell scripts to generate dvc.yaml files is needed to complete this update. See https://github.com/iterative/dvc.org/pull/1637#discussion_r463117077~~ Now part of #2076

[vibhor98]

Hi @shcheklein, I would like to take up this issue. Thanks!

[jeremydesroches]

No problem at all. I was hoping to work on an issue that required a bit of investigation and discussion. I learned a lot, so mission accomplished!

So based on your discussion (haha) it sounds like the the current PR won’t need much more adjustment. I’ll find a newer issue to work on next. (Please let me know if any suggestions or preferences.)

BTW this isn’t possible, dvc.yaml doesn’t accept any sort of variables, it’s just YAML.

I see, so you couldn’t have a dvc.yaml file with a $(dvc root) variable — but you could use $(dvc root) in the script to generate a dvc.yaml file with references to the root directory, relative to the working directory where the script is run. Right?