dep_doc

Add a cute dependency declaration snippet in your crate documentation.

Adding to Cargo.toml

[dependencies]
dep_doc = "0.1.1"

Goal

When writing Rust libraries, it is quite common to add a code snippet which shows to the end-user how to add the crate to the Cargo.toml. The problem is that there's no way to ensure that the crate name and version are correct before releasing a new version.

This crate aims to automate the TOML snippet generation by providing macro-assisted solution which expand in the correct crate name and version. It does so by reading environment variables that are set by cargo itself.

Usage

To add the TOML snippet, insert the following line between two documentation lines:

//! Some doc...
#![doc = dep_doc::dep_doc!()]
//! Some other doc

If invoked in dep_doc, this will generates the following documentation:

Some doc...

[dependencies]
dep_doc = "0.1.1"

Some other doc

Customization

Some crates may document specific features, git repository, branches, commit hash, and so on. This can be addressed by passing code in the dep_doc invocation:

//! Some doc...
#![doc = dep_doc::dep_doc!(git = "https://github.com/scrabsha/dep-doc")]
//! Some other doc

If invoked in dep_doc, this will generate the following documentation:

Some doc...

[dependencies]
dep_doc = { version = "0.1.1", git = "https://github.com/scrabsha/dep-doc" }

Some other doc

My library is better suited as a development dependency

That's fine! dev_dep_doc generates the appropriate documentation. It replaces the [dependencies] section by a [dev-dependencies] one.

//! Some doc...
#![doc = dep_doc::dev_dep_doc!(features = ["proc_macro", "no_std"])]
//! Some other doc

If invoked in dep_doc, this will generate the following documentation:

Some doc...

[dev-dependencies]
dep_doc = { version = "0.1.1", features = ["prod_macro", "no_std"] }

Some other doc

License