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

announcements
1

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
2

reminds me of @epage's docmatic:

https://github.com/assert-rs/docmatic

3

and of cargo-readme

4

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
5 
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?

6

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
7

Thanks for clarifying the suggested workflow.

Not seeing it in your readme, mind adding it?

1 Like
8

I'll add more documentation ASAP...

1 Like