4 ms·
I wish people would find a way to include any code present in a README in some kind of automated test. Nothing more frustrating than if you copy something from
by noxer 6y ago
I wish people would find a way to include any code present in a README in some kind of automated test.
Nothing more frustrating than if you copy something from there but it turns out the README wasn't updated since the very first day and all the "hello world" code or install instructions are completely outdated
Maybe not include any code is the better solution, instead add an example folder.
- franciscop 6y agoI did that! I hope you are not the person who suffered that from me (did you use Picnic CSS a few years back?). So for a newer project I put some setup code that will look for all code snippets with a specific comment and run that with the code after the comment. For generating the website documentation that test bit can be stripped (though I kept it for now). Example: https://github.com/franciscop/server/blob/master/docs/documentation/options/README.md#public https://github.com/franciscop/server/blob/master/docs/docume...
- kstenerud 6y agoOne thing golang did right is the go playground. When I put code in my README, I also include a playground link. Example: https://github.com/kstenerud/go-concise-encoding#library-usage https://github.com/kstenerud/go-concise-encoding#library-usa...
- Gadiguibou 6y agoThat's included in Rust![1] Code examples from the documentation automatically become "documentation tests" to make sure your examples are still up to date when updating your code. [1] https://doc.rust-lang.org/rustdoc/documentation-tests.html https://doc.rust-lang.org/rustdoc/documentation-tests.html
- Omin 6y agoThe README.md isn't part of the rust code, so it's not checked by this unless you use tools to generate your README from doc comments like https://github.com/livioribeiro/cargo-readme https://github.com/livioribeiro/cargo-readme.
- Rompect 6y agoActually, it's possible and even frequently used, for example in lazy-static, through the `doc_comment` crate. #[cfg(doctest)] #[macro_use] extern crate doc_comment; #[cfg(doctest)] doctest!("../README.md"); Now, the readme examples are tested like everything else. https://github.com/rust-lang-nursery/lazy-static.rs/blob/master/src/lib.rs#L105 https://github.com/rust-lang-nursery/lazy-static.rs/blob/mas...
- thejosh 6y agoI like this about elixir, in the documentation you can use exdoc to make sure that the code examples actually work, and provide code samples that are tested. It makes reading documentation for projects quite nice.
- an_ko 6y agoI've written this tool to test example code in markdown documents using user-specified shell commands: https://github.com/anko/txm https://github.com/anko/txm I have had great success using it in my own projects, so perhaps others might find it useful too.
- SuperCuber 6y agoI do something similar: my README contains the output of --help, and I have a CI step that ensures that all the lines of the actual help output are present in the README. Caught me a couple times forgetting to update new flags and version changes.
- M3t0r 6y agoI've spent hours putting that functionality into a unit test. Worth every minute!
- ehershey 6y agoThis is brilliant! It’s one of those things that’s so easy to forget or not even think about but once you see it or think about it, it’s essential.
- kevin_thibedeau 6y agoGenerate it with an m4 include.
- tele_ski 6y agoThis is great advice and I wish it was the standard. I had this problem on one of my projects so I used a githook to basically paste in actual compiled example files from the test suite on committing. It does mean the actual readme is more like a template and you can't edit the README file directly anymore but all the examples always work now! I personally like at least one small example embedded in the README since it's zero effort, an example folder is great for _more_, but annoying to get started, what should I look at in the example folder first?
- boxed 6y agoYou'll like this https://kodare.net/2020/10/23/100_percent_coverage_docs.html https://kodare.net/2020/10/23/100_percent_coverage_docs.html it's my journey to 100% coverage for all code samples in ALL the documentation for iommi.
- Liskni_si 6y agoI've been using https://github.com/brodie/cram https://github.com/brodie/cram for this. It's a neat little shell testing tool that can be told to check that every 4-space indented markdown code block output what it says it outputs, so I just cram my README.md. An example of this in action: https://github.com/liskin/liscopridge/blame/68a656b7beb10a5cda6d2f822366de8bddd53a88/src/liscopridge/app/statshunters.md#L14-L26 https://github.com/liskin/liscopridge/blame/68a656b7beb10a5c..., https://github.com/liskin/liscopridge/blob/68a656b7beb10a5cda6d2f822366de8bddd53a88/Makefile#L47-L53 https://github.com/liskin/liscopridge/blob/68a656b7beb10a5cd...