Rust Skeptic - Test your Rust Markdown documentation via Cargo

1

Announcing the initial release of Rust Skeptic, a tool for testing Markdown files (ala rustdoc) directly from Cargo. Details are in the README file.

My initial use case for this is adding verified examples to stdx, which can further be incorporated into crater-based language regression testing.

6 Likes
2

At long list I have published version 0.5.0 of rust-skeptic, the tool for testing Markdown files via Cargo. Skeptic is similar to rustdoc --test but has a slightly more principled design and integrates with Cargo to test single mardown files.

0.5.0

Thanks to skeptic contributors: Brian Anderson, Christopher Brickley, Johann Hofmann, Paul Osborne, Ryman

You may also be interested in @pnkfelix's tango, a similar but different tool.

1 Like
3

rust-skeptic 0.6 is out. This contains one fix for no_run. Thanks @HessiJames!

0.6.0

4

rust-skeptic 0.6.1 is out!

0.6.1

Contributors: Brian Anderson, Markus, Oliver Schneider

5

Last week I released skeptic 0.7.1.

The big change in this version is that, finally, I've fixed the bug that caused rustc to get confused by multiple versions of dependencies in the target folder. This should make it much more reliable.

Skeptic remains a good choice for testing documentation that must link to crates. It works well with mdbook, as I'm using it in rust-cookbook.

1 Like
6

I've just released skeptic 0.8.1.

This release features a more flexible template system (the old still works). Here's the description from the README:

Unlike rustdoc, Skeptic does not modify examples before testing by
default. Skeptic examples are placed in a '.rs' file, compiled, then
run.

This means that - by default - Skeptic examples require a main
function, as in all the examples above. Implicit wrapping of examples
in main, and custom injection of extern crate statements and crate
attributes are controlled through document-level templates.

Templates for a document are located in a separate file, that lives
next to the document on the filesystem, and has the same full name as
the document file, but with an additional ".skt.md" template.

So for example, this file, README.md, stores its templates
in README.md.skt.md.

This scheme allows the markdown to be displayed naturally be stock
Markdown renderers without displaying the template itself. The weird
file extension is similarly so that the templates themselves are
interpreted as valid markdown while being easy to ignore based on file
system.

Consider this example:

let p = PathBuf::from("foo");
println!("{:?}", p);

This example won't compile without defining main and importing
PathBuf, but the example itself does not contain that
boilerplate. Instead it is annotated skt-foo, for skeptic template
foo, like so:

 ```rust,skt-foo
let p = PathBuf::from("foo");
println!("{:?}", p);


This tells skeptic to look in the template file for another
markdown block with the same `skt-foo` annotation, and composes
them together using the standard Rust `format!` macro. Here's
what the template looks like:

```rust,ignore
 ```rust,skt-foo
use std::path::PathBuf;

fn main() {{
    {}
}}
1 Like
7

I am planning to use Skeptic to test all of the code samples on https://serde.rs. @brson one thing I need is the thing that rustdoc does where it ignores lines starting with "#". I made a PR:

https://github.com/brson/rust-skeptic/pull/21

8

Skeptic 0.9.0 is out. This release includes the ability to strip rustdoc-style # ignored line markers.

0.9.0

Contributors: Brian Anderson, David Tolnay

1 Like
9

@dtolnay Before committing to skeptic you should review this bug, which causes crate resolution failures with some regularity.

10

Thanks, I worked around it already yesterday. Mostly I care about running Skeptic in CI where it starts with a clean directory anyway, so it won't bother me.

11

Skeptic 0.10.0 is out. This release makes tests run with the current directory set to a temporary directory so that any files produced as side-effects don't pollute the project directory.

0.10.0

Contributors: Brian Anderson, Michal Budzynski

12

Another bugfix release. Thanks @budziq.

0.10.1

Contributors: Brian Anderson, Michal Budzynski

13

This release fixes, for most cases, the major bug where skeptic failed to resolve multiple duplicate dependencies. Thanks @budziq.

0.11.0

Contributors: Brian Anderson, Michal Budzynski

14

Some recent changes released to crates.io

0.12.3

Contributors: Michal Budzynski, Frank McSherry

0.12.2

Contributors: Michal Budzynski

0.12.1

Contributors: Michal Budzynski

0.12.0

Contributors: Brian Anderson, Chris Butler, Michael Howell, Victor
Polevoy

15

This version fixes long standing problem with local and vcs dependency path resolution (since 0.11.0) and few other minor problems.

0.13.0

Contributors: Michał Budzyński, Simon Baptista

1 Like