cargo-insert-docs

Overview

cargo-insert-docs does two independent tasks

1. Inserts feature documentation from Cargo.toml into your crate docs.
2. Inserts crate documentation from lib.rs into your README.md.

You can use either task on its own by disabling the other with --no-feature-docs or --no-crate-docs.

Installation

# If you have `cargo-binstall` installed:
cargo binstall cargo-insert-docs

# Otherwise
cargo install cargo-insert-docs

For the "Inserts crate documentation from lib.rs into your README.md"-part of cargo-insert-docs, you need to have a recent nightly toolchain installed. See Compatibility.

rustup install nightly --profile minimal

Usage

Add feature documentation to your Cargo.toml using ## for documentation of individual features and #! to add documentation between features:

[features]
default = ["std", "jpg"]

## Enables loading [`Image`]s from [`std::io::Read`].
std = []

#! ## Image formats
#! The following formats are supported.

## Enables support for jpg images
jpg = []

## Enables support for png images
png = []

Then add a feature documentation section to your lib.rs file:

//! Use the [Image] type to load images.
//!
//! # Feature Flags
//! <!-- feature documentation start -->
//! <!-- feature documentation end -->
//!
//! # Examples
//! ```
//! # use example_crate::Image;
//! let image = Image::load("cat.png");
//! # println!("this won't show up in the readme");
//! ```

And add a crate documentation section to your README.md:

# my-crate-name

Badges go here.

<!-- crate documentation start -->
<!-- crate documentation end -->

License goes there.

Now run cargo-insert-docs:

cargo insert-docs

Then your lib.rs will end up looking like this:

//! Use the [Image] type to load images.
//!
//! # Feature Flags
//! <!-- feature documentation start -->
//! - **`std`** *(enabled by default)* — Enables loading [`Image`]s from [`std::io::Read`].
//!
//! ## Image formats
//! The following formats are supported.
//!
//! - **`jpg`** *(enabled by default)* — Enables support for jpg images
//! - **`png`** — Enables support for png images
//! <!-- feature documentation end -->
//!
//! # Examples
//! ```
//! # use example_crate::Image;
//! let image = Image::load("cat.png");
//! # println!("this won't show up in the readme");
//! ```

And your README.md will look like that: (tests/example-crate/README.md)

# my-crate-name

Badges go here.

<!-- crate documentation start -->
Use the [Image](https://docs.rs/example-crate/0.0.0/example_crate/struct.Image.html) type to load images.

## Feature Flags
<!-- feature documentation start -->
- **`std`** *(enabled by default)* — Enables loading [`Image`](https://docs.rs/example-crate/0.0.0/example_crate/struct.Image.html)s from [`std::io::Read`](https://doc.rust-lang.org/std/io/trait.Read.html).

### Image formats
The following formats are supported.

- **`jpg`** *(enabled by default)* — Enables support for jpg images
- **`png`** — Enables support for png images
<!-- feature documentation end -->

## Examples
```rust
let image = Image::load("cat.png");
```
<!-- crate documentation end -->

License goes there.

To update the sections just run the command again.

You don't have to add both sections for the tool to work. If it doesn't find a section it will just carry on with a warning. You can turn that warning into an error with the --strict flag.

You can find details about all the available arguments in docs/cli.md.

Compatibility

To extract the crate documentation cargo-insert-docs relies on the unstable rustdoc JSON format, which requires a recent Rust nightly toolchain to be installed.

A new nightly release may no longer be compatible with the current version and cargo-insert-docs will need to be updated. Alternatively you can choose a specific nightly version that is known to be compatible using the --toolchain argument.

Compatibility Matrix

Similar projects

• document-features: https://crates.io/crates/document-features
• cargo-readme: https://crates.io/crates/cargo-readme
• cargo-rdme: https://crates.io/crates/cargo-rdme

License

Licensed under either of:

• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
• Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)

at your option.

This project includes code adapted from the Rust standard library (https://github.com/rust-lang/rust),
Copyright © The Rust Project Developers. Such code is also licensed under MIT OR Apache-2.0.

Your contributions

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.