Hacker News Reader

One of my personal pet peeves is when library examples don't actually work anymore due to API changes (or typos).

There's actually a really great solution in the Rust ecosystem that I would love to see used more widely - Skeptic [0]. It's a tool that parses markdown, finds Rust and builds it as an auto-generated test. If the example is no longer valid, it breaks your build.

[0] - https://github.com/budziq/rust-skeptic

View on HN

Another approach which I've liked in the past to solve this issue is to generate your README's from Rust Source. This has the same net output but the readme lives within Rustdoc.

I think I prefer it living in Rustdoc because then your README is also on docs.rs and whatnot.

But, I can see some downsides with that too. Not every README should be identical to the API docs. Not sure where the balance should sit.

So, to be clear, skeptic helps with extra markdown files you've written. Rustdoc will already do this with every example you write in your API documentation. It's very good though! (mdbook has a similar feature)

Good point - thanks for calling it out!

Reply on news.ycombinator.com