Best practice for doc testing README

help
1

It is very common that a crate may provide one single README.md for both GitHub main page, crates.io main page, root-level rustdoc, and even mdbook preface. Moreover, both rustdoc and mdbook provide capability to conduct doc tests on Rust codes in README, which is helpful to make sure that the codes provided in Usage or Example work as it is.

However, to make the doc test work, we must provide a whole working code snippet, which involves many items that distract readers (for example, we may want just a struct name or function name, but we need to explicitly define those items). Rustdoc and mdbook support to add a # prefix in the line to indicate the line is hidden from readers. While GitHub and crates.io do not support this, and readers from those platform will see ugly # lines.

I wonder what is the best practice to provide such README file, which can be doc tested and not to distract GitHub and crates.io readers by the # lines.

2

This is a great question. I think the best answer is cargo-readme. It generates your readme from your lib.rs and is pretty smart about it, removing hidden lines from doctests and adding badges and licence from Cargo.toml.

You can even template out the generated README to add stuff that doesn't really belong in the docs, or just lay things out differently to suit your preference.

1 Like
3

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.