[Announcement] doubter, a crate for testing code blocks in Markdown

Today I’ve published a tiny crate doubter, which helps testing code blocks in Markdown files.

The approach adopted by doubter is to embed Markdown files as doc-comments into Rust source code. It is corresponding to the unstable attribute #[doc(include = "...")], but doubter makes it possible to use it on the stable compiler by emulating it as a procedural macro.

Currently, the crate is the experimental stage and I’m looking for feedback from many users. If you are interested, let’s try it and send issue or PR.

Thanks.

1 Like

reminds me of @epage’s docmatic:

and of cargo-readme

So to contrast

  • Nightly #![doc(include = "...")] brings your markdown into your code
    • Personally, I like having separate README.md from lib.rs doc comment
  • cargo-readme turns rustdoc-tested doc comments into markdown files
    • Personally, I like having separate README.md from lib.rs doc comment
  • Skeptic parses markdown and generates test files
    • Suffers from errors when mixed with cargo check
    • Markdown parser slows down full rebuilds
    • Using build.rs foists this on clients that don’t care (never looked into hiding it behind a feature flag)
  • Docmatic runs rustdoc on markdown
    • Suffers from errors when mixed with cargo check
    • Avoids the other pitfalls of skeptic.
  • doubter turns markdown files into doc comments for macro-generated items

Doubter seems like it has the potential to be the least problematic.

2 Likes
Ok(quote!(
    #[doc = #content]
    pub const #constant_name : () = ();
))

Does rustdoc pick these up and put them docs.rs? If so, how do we avoid this?

It assumes that the crate for testing Markdowns with doubter is not subject to publication and separated with the crate to be tested (so the testing crate is often managed in workspace). As a result, doc comments generated by doubter will not be appear in the published crate.

2 Likes

Thanks for clarifying the suggested workflow.

Not seeing it in your readme, mind adding it?

1 Like

I’ll add more documentation ASAP…

1 Like