docs: List instances of stage file concepts, dvc run/checkout/repro for example review and update to 1.0

[jeremydesroches]

From #1255 :

Create a list of places where the concept of stage file(s) and dvc run/checkout/repro are used...

List of places here, including initial example:

Get Started

• https://dvc.org/doc/start/data-pipelines
• https://dvc.org/doc/start/experiments
• Several cmd examples/links need updating (see Command Reference section below)

User Guide

• https://dvc.org/doc/user-guide/dvc-files-and-directories
• https://dvc.org/doc/user-guide/managing-external-data
• https://dvc.org/doc/user-guide/external-dependencies
• https://dvc.org/doc/user-guide/related-technologies
• https://dvc.org/doc/user-guide/large-dataset-optimization
• https://dvc.org/doc/user-guide/merge-conflicts
• https://dvc.org/doc/user-guide/dvcignore

Use Cases

• https://dvc.org/doc/use-cases/versioning-data-and-model-files/tutorial

Install

• https://dvc.org/doc/install/completion - docs: replace stage file example in /install/completion, fix typos found in review #1766

Command Reference

• https://dvc.org/doc/command-reference/run
• https://dvc.org/doc/command-reference/repro
• https://dvc.org/doc/command-reference/remove
• https://dvc.org/doc/command-reference/freeze - docs: replace stage file example in /install/completion, fix typos found in review #1766
• https://dvc.org/doc/command-reference/unfreeze- docs: replace stage file example in /install/completion, fix typos found in review #1766
• https://dvc.org/doc/command-reference/update
• https://dvc.org/doc/command-reference/dag - docs: replace stage file example in /install/completion, fix typos found in review #1766
• https://dvc.org/doc/command-reference/fetch
• https://dvc.org/doc/command-reference/import - ok, get started examples/links need updating
• https://dvc.org/doc/command-reference/import-url - ok, get started examples/links need updating
• https://dvc.org/doc/command-reference/commit - ok, get started examples need updating
• https://dvc.org/doc/command-reference/pull
• https://dvc.org/doc/command-reference/params
• https://dvc.org/doc/command-reference/params/diff - run example out of date (fixed in Updates metrics show and Plots diff example as per 1.0 #1908)
• https://dvc.org/doc/command-reference/push
• https://dvc.org/doc/command-reference/checkout - ok, get started examples need updating
• https://dvc.org/doc/command-reference/metrics - ok, get started example/link needs updating
• https://dvc.org/doc/command-reference/metrics/diff
• https://dvc.org/doc/command-reference/metrics/show - references stage file example from get started
• https://dvc.org/doc/command-reference/status
• https://dvc.org/doc/command-reference/plots/show
• https://dvc.org/doc/command-reference/plots/modify
• https://dvc.org/doc/command-reference/install - docs: replace stage file example in /install/completion, fix typos found in review #1766
• https://dvc.org/doc/command-reference/config
• https://dvc.org/doc/command-reference/diff - cmd: update diff examples for dvc 1.0 #1965

Second part from #1255, which may be better as second issue:

We should review all those docs to make sure the use of dvc run/etc and YAML examples are updated to 1.0.

(Items in list above will be checked when checked/updated.)

[jeremydesroches]

@jorgeorpinel I'll list the issues as shown. Should the second part remain here or be its own issue?

[jorgeorpinel]

Nice, thanks @jeremydesroches. Let's keep the 2nd part here for now. I edited the description above a bit.

[jorgeorpinel]

Hey @jeremydesroches I see (almost) all the check boxes are marked now, but only a few are addressed in PR #1766. Can you explain what happened? Thanks

[jeremydesroches]

Yes, I reviewed all the items in the list and marked them as follows:

• checked off items with examples and dvc run/etc that apply 1.0 usage
• added link to PR "docs: replace stage file example in /install/completion, fix typos found in review #1766" on items where I made edits following review
• checked off "ok" items but added notes where examples need other updates (out of date with current getting started, etc.)
• left items unchecked that have examples with pre-1.0 usage and need updates as part of this issue

[jorgeorpinel]

Got it. Glad to see most of it is done then. Are you planning to finish this one off then? Or would you rather turn to SEO work at this point?

[jeremydesroches]

Happy to finish off the updates for the unchecked items. I think the checked items that need getting started references updated should be taken up in a new issue (or an appropriate existing one).

[jorgeorpinel]

OK. Also the 2nd part may be pending (dvc run/repro and YAML examples).

[jorgeorpinel]

@jeremydesroches do you think we can finish addressing this issue? The few checkboxes left seem pretty straight-forward.

[jeremydesroches]

Yep @jorgeorpinel I'm on it. I'll work through the last unchecked items and verify/update the get started examples.

[jorgeorpinel]

Note that the example-get-started repo is no longer used directly in https://dvc.org/doc/start so you could just follow the steps manually @jeremydesroches.

BTW

checkout - ok, get started examples need updating

That command is only used in https://dvc.org/doc/start/data-versioning and seems correct (wouldn't hurt to double check though).

[jorgeorpinel]

@jeremydesroches you can strikethrough or remove the bullets involving "get started" because that will have to be rewritten soon anyway. Is there anything else left here? Thanks

[jeremydesroches]

Is there anything else left here?

OK @jorgeorpinel, struck out the "get started" bullets. Nope, nothing left here.

[jorgeorpinel]

Well, thanks for taking care of it!