Crate dep_doc[−][src]
Expand description
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 = ["proc_macro", "no_std"] }
Some other doc
Macros
Generates a Cargo.toml
code snippet showing how to add the current crate
as a dependency.
Generates a Cargo.toml
code snippet showing how to add the current crate
as a dev-dependency.