Some commands are "unrunnable"

[ghost]

For example, the following snippet from: https://dvc.org/doc/commands-reference/metrics

dvc run -d code/evaluate.py \
        -M data/eval.json \
        -f Dvcfile \
        python code/evaluate.py

I can't run the following command because I lack code/evaluate.py.

It would be great to have either:

1. The command used above ready to copy paste, for example:

# code/evaluate.py
print("do some evaluation...")

2. Use more broad commands that the user can actually copy paste, like echo or whatever.

[shcheklein]

It's a good question! What are your thoughts, @dmpetrov @robogeek ?

I personally prefer them to be "executable". Like in dvc repro - a simple pipeline out of bash commands. But on the other hand, there is an opinion that we should use some domain that is close to the real-life in all our examples. It's extremely hard to make them executable obviously (that's what get started, tutorials, full examples are).

We haven't figured out the right balance here still I believe.

[robogeek]

Yes I've seen the discussion on the forum asking that the examples be directly executable.

I think the tail end of command documentation is not the place to put an extensive example with all the bells and whistles. Therefore those examples have to be minimalized using simple tools.

I also think the example section in command documentation should be seen as a broad example of what might be done, rather than a concrete executable example -- but obviously the voice of the customer as spoken in the forum says differently.

[robogeek]

FWIW I've just added a detailed example showing what happens in the cache from a dvc push operation. The example is attached to this pull request:

#203

[shcheklein]

@robogeek @MrOutis I've updated the dvc checkout example here: https://dvc.org/doc/commands-reference/checkout. It should be "runnable". It's a tradeoff in terms of complexity vs keeping it runnable. @MrOutis you still need to clone the repo and install requirements to being able to run it. I think we can do echo, wc -l as well, to show the concept even in a simpler environment.

Let me know what you think guys.

[shcheklein]

Duplicate #198