Cargo rdme
Cargo command to create your README from your crate’s documentation.
Installation
You can install cargo rdme with cargo by running cargo install cargo-rdme.
Usage
Cargo rdme will insert your crate’s documentation in your README file. To control where the documentation will be inserted you need to insert a marker: <!-- cargo-rdme -->. For example, you can start your README with some glorious badges and follow up with the rustdoc documentation:
[](https://example.org/link-to-ci)
<!-- cargo-rdme -->
After running cargo rdme you will find your README to be something like:
[](https://example.org/link-to-ci)
<!-- cargo-rdme start -->
<WHATEVER-YOUR-CRATES-DOC-IS>
<!-- cargo-rdme end -->
Whenever change your crate’s documentation you just need to run cargo rdme to update your README file.
Automatic transformations
The documentation of your crate doesn’t always map directly to a good README. For example, rust code blocks can have hidden lines. Those should not be shown in the README file.
This section covers the transformation cargo rdme automatically apply to generate a better README.
Rust code block
Rust code block are transformed in two ways by cargo rdme:
- Rust code blocks with lines starting with
#will be omitted, just like inrustdoc. - Rust code blocks get annotated with the
rustmarkdown tag so it gets proper syntax highlighting. We also remove tags that only concernrustdocsuch asshould_panic.
In the table below you can see an example of these modification. The code block now is tagged with rust and hidden lines were removed:
| Crate’s rustdoc | README.md |
|---|---|
//! To check if a number is prime do:
//!
//! ```
//! # fn main() {
//! for i in 2.. {
//! if is_prime(i) {
//! println!("{}", i);
//! }
//! }
//! # }
//! ```
|
To check if a number is prime do:
```rust
for i in 2.. {
if is_prime(i) {
println!("{}", i);
}
}
```
|
Intralinks
Rust documentation can contain links to items defined in the crate. This links would not make sense in your README file, so cargo rdme automatically generate links to docs.rs for these intralinks.
Currently we only support links of the form [⋯](crate::⋯), so be sure to use that format. Links to the standard library are also supported, and they must be of the form [⋯](::<crate>::⋯), where <crate> is a crate that is part of the standard library, such as std, core, or alloc.
Take a look at the example below:
| Crate’s rustdoc | README.md |
|---|---|
//! To check if a number is prime use
//! [`is_prime`](crate::is_prime).
|
To check if a number is prime use
[`is_prime`](https://docs.rs/prime/latest/prime/fn.is_prime.html).
|
Note that there is some limitations in intralink support. This is a complex feature: cargo rdme needs to do some work to be able to create the link to docs.rs. This is because the link includes the kind of item the intralink points to, in the case of is_prime we need to discover that is a function to generate a link that ends in fn.is_prime.html. Therefore, intralink support should be considered "best effort" (for instance, don’t expect items generated by macros to be resolved). If cargo rdme is unable to generate the link it will still generate the README file, but a warning will be emitted.
Configuration file
If the default behavior of cargo rdme is not appropriate for your project you can crate a configuration file .cargo-rdme.toml in the root of your project. This is how that configuration file can look like:
# Override the README file path. When this is not set cargo rdme will use the file path defined
# in the project’s `Cargo.toml`.
readme-path = "MY-README.md"
# What line terminator to use when generating the README file. This can be "lf" or "crlf".
line-terminator = "lf"
# If you are using a workspace to hold multiple projects, use this to select the project from
# which to extract the documentation from. It can be useful to also set `readme-path` to create
# the README file in the root of the project.
workspace-project = "subproject"
# The default entrypoint will be `src/lib.rs`. You can change that in the `entrypoint` table.
[entrypoint]
# The entrypoint type can be "lib" or "bin".
type = "bin"
# When you set type to "bin" the entrypoint default to `src/main.rs`. If you have binary targets
# specified in your cargo manifest you can select them by name with `bin-name`.
bin-name = "my-bin-name"
These setting can be overridden with command line flags. Run cargo rdme --help for more information.
Integration with CI
To verify that your README is up to date with your crate’s documentation you can run cargo rdme --check. The exit code will be 0 if the README is up to date, 2 if it’s not, or 4 if there were warnings.
14 Dec 29, 2022
367 Dec 21, 2022
120 Dec 19, 2022
564 Nov 15, 2022
101 Dec 29, 2022
20 Jan 8, 2023
20 Sep 11, 2022
79 Dec 12, 2022
60 Oct 28, 2022
997 Jan 4, 2023
12 Jun 10, 2021
8.2k Jan 8, 2023
13 Nov 14, 2021
776 Dec 30, 2022
38 Dec 30, 2022
2 Dec 14, 2022
6 Feb 27, 2022
83 Dec 15, 2022
36 Jul 16, 2024
20 Nov 9, 2020