cargo-insert-docs 0.2.0

# cargo-insert-docs

[![Crates.io](https://img.shields.io/crates/v/cargo-insert-docs.svg)](https://crates.io/crates/cargo-insert-docs)
[![License](https://img.shields.io/crates/l/cargo-insert-docs)](#license)
[![Build Status](https://github.com/bluurryy/cargo-insert-docs/workflows/Release/badge.svg)](https://github.com/bluurryy/cargo-insert-docs/actions/workflows/release.yml)

## 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

```sh
# 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](#compatibility).

```sh
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:
```toml
[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:
```rs
//! 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`:
```md
# my-crate-name

Badges go here.

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

License goes there.
```

Now run `cargo-insert-docs`:
```sh
cargo insert-docs
```

Then your `lib.rs` will end up looking like this:
```rs
//! 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](tests/example-crate/README.md))
````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](docs/cli.md).

## Compatibility

To extract the crate documentation `cargo-insert-docs` relies on the unstable [rustdoc JSON](https://github.com/rust-lang/rust/issues/76578) 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`](docs/cli.md) argument.

#### Compatibility Matrix

|Version|Understands the rustdoc JSON output of|
|---|---|
|0.1.x|nightly-2025-06-22 — ?|

## 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](LICENSE-MIT) or <https://opensource.org/licenses/MIT>)
 * Apache License, Version 2.0, ([LICENSE-APACHE](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.