docmatic

Be dogmatic about working documentation.

Usage

First, add this to your Cargo.toml:

[dev-dependencies]
docmatic = "0.1"

Next, in your test file:

extern crate docmatic;

fn test_readme() {
    docmatic::assert_file("README.md");
}

For more information on using docmatic, look at the documentation

Why Docmatic?

Compared to doing nothing:

• When you have stale documentation, it gives a sour taste to those considering your crate

Compared to #![doc(include = "../README.md")]

• Allows your README to focus on potential contributors and your API docs on potential users
• Doesn't require nightly

Compared to rustdoc -L target/debug/deps/ --test README.md

• Docmatic pros:
  • Easier for contributors to know how to run
• rustdoc pros:
  • Simple
  • No dependencies to muck with

Compared to skeptic:

• Docmatic pros:
  • Fewer dependencies for faster build
  • Doesn't require exposing those dependencies to your users via a [build-dependencies]
  • Runs in the expected working directory
• Skeptic pros:
  • Skeptic templates
  • Better integration with cargo test (each block is a distinct test)

See doc-comment for another aproach.

License

docmatic is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE, and LICENSE-MIT for details.

Credits

We're grateful for all of the work done on skeptic, the spiritual predecessor to docmatic and the work of people iterating on a lighter weight solution.