runnableExamples that are only compiled

[FedericoCeratto]

runnableExamples are run by nim doc. Some code examples should not be run due to side effects or other reasons, but parsing and compiling the code is still beneficial to prevent code rot.

For example: httpclient fetching a remote URL; deleting files; and so on.

This can become quite dangerous when running nim doc on 3rd party libraries where the authors might have written examples without realizing they would be execute automatically!

[juancarlospaco]

runnableExamples:
  if off:
    echo "I am and example, but too lazy to Run"

❔

[alaviss]

runnableExamples:
  proc main() =
    echo "I'm not running"

^ that's also a way.

[FedericoCeratto]

Any "if false", "when false", "def main" line is confusing to people reading the examples (as they are unaware of the hack). Also nim doc still tries to execute the file without need.

[Araq]

Non-running runnable examples are confusing, you might as well use .. code-block:: nim for the example then.

[FedericoCeratto]

@Araq the code-block renders differently and (as you said before) leads to code rot. I guess proc example() could be the least confusing:

runnableExamples:
  proc example() =
    echo "I'm not running"

[timotheecour]

fixing this more generally in #14384, which allows passing an arbitrary cmd

[FedericoCeratto]

This sounds like a good use-case for the Effect system - if there was a way to ensure that examples are not doing I/O and other unwanted activities.