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

[shcheklein]

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

i.

• [x] The layout of this command reference is outdated.

• [x] It should be the same as for the cache for example.

ii.

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

• [x] 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!

[shcheklein]

Partially done by @vibhor98 . I've updated the description a little considered the changes done.

[jeremydesroches]

@jorgeorpinel I’ll work on closing this out.

[jorgeorpinel]

@shcheklein the first bullet states "motivation for this command - mostly ease of generating stage files no matter where you use dvc run". Actually, we no longer see run as the main and recommendad way to generate dvc.yaml files, so is that motivation still valid? I think almost. Maybe something more like "ease of generating stages in dvc.yaml files programmatically or with the dvc run helper command, regardless of where it's used."

Cc @jeremydesroches - does this make sense to you? You may want to review https://dvc.org/doc/user-guide/dvc-files-and-directories and https://dvc.org/doc/command-reference/run 🙂

P/s feel free to contact me with questions or even faster at out Discord channel dvc.org/chat

[jeremydesroches]

@jorgeorpinel Yes, that does make sense to me. The examples work with dvc run, but don't seem as useful as direct or programmatic usage in dvc.yaml files. If the recommended use and primary motivation is to use it in dvc.yaml files then the examples could be updated too.

[jorgeorpinel]

Yes, that does make sense to me

Great! Please use the motivation I suggested as the guiding idea for finishing updating the command's description, Jeremy.

then the examples could be updated too.

I agree, but let's keep the current PR small for now, and just update the existing content or remove examples if they're no longer relevant? Leaving it for another PR to add new ones (so please don't use the special word "Fixes" in the PR description for now). Thanks

ALTHOUGH by programmatically we basically mean shell scripts here I think (since dvc root is a command)... And I'm not sure people will generate dvc.yaml files with shell scripts very often. I guess you can invoke the command from any programming language to... But for Python specifically there's probably a better way using the dvc module.

So maybe let's wait to see what @shcheklein says. Let me also ping @efiop (hi) — what are the use cases of dvc root in 1.x? Thanks! UPDATE: Never mind, sorry Ruslan.

[jeremydesroches]

OK, I'll wait for comments before updating motivation and examples. I can see how it might be used in a script to "template" an experiment or stage to be used in different projects, but that type of example might be too detailed for a command reference.

Removed "Fixes" from the PR description.

[jorgeorpinel]

Thank you. I'm thining hard about this rn. Maybe I'll come up with an answer... Give me a few ⏳

[jorgeorpinel]

Sorry I let you start working on this without thinking it through. It's just a pretty old issue... But anyway!

OK, I had a discussion with myself (and found a previous conversations in https://github.com/iterative/dvc.org/pull/408) and yes, it's main use cases seem to be 1) as a way to get the project root from shell scripts that generate dvc.yaml files either with the dvc run helper or programmatically in some other way; and 2) to embed it directly in dvc run (only POSIX terminals).

So the current Examples are OK topic-wise (just need to be "actionable and meaningful" as described above), but another one with an actual shell script (for Linux) would be nice (not required for your current PR @jeremydesroches).

direct or programmatic usage in dvc.yaml files

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

[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?

[jorgeorpinel]

Yep, just to address the couple reviews already open in #1637 should wrap it up.

Right?

Correct. Once generated, they would be hard coded in dvc.yaml (or in a .dvc file for that matter, since you could do something like dvc add $(dvc root)/data/words.txt. See https://dvc.org/doc/command-reference/add if you haven't 🙂

[jorgeorpinel]

OK, #1637 almost closed this (thanks @jeremydesroches) but we still need that shell script example. I updated the description of this issue (who knew it would be so hard to close...)

[jorgeorpinel]

This is mostly done. Moved the remaining part to #2076. Closing!