Do not duplicate example code in README
tshepang opened this issue · 3 comments
It feels clumsy having to maintain copies of the same code (examples/ and README). Also, that README is rather large with all those examples. How about just linking to the examples?
I agree it's quite annoying to have to keep the two in-sync, and I'm not sure whether it's providing value to have them in two separate places. I think I was originally thinking it was nice to be able to run cargo run --example fnv etc., but I don't know if users will ever actually do that. I was also thinking that the examples can be more easily tested than the docs, though presently there's no testing at all.
I am though reluctant to move the examples out of the documentation, though your point that the docs are getting pretty big is well taken.
Another possibility is to remove the standalone examples and test the docs.
Another possibility is to add a custom lint that checks that the two stay in sync. I don't particularly care about the maintenance burden as long if the duplication is worthwhile; though again I'm not sure if having the examples in two places is worthwhile.
I'm not sure yet what I want to do about this.
In that case, how about we only have these examples in the README. They are short enough to just copy-paste. Another idea is to generate the README maybe from a template with the help of a tool that reads content of examples/.
README could include the example files, but GitHub markdown doesn't implement an include feature and its implementation of .rst files disables the ..includedirective. So including (or separating out) the example files would have to be a separate step.