16 releases
0.3.9 | Oct 19, 2024 |
---|---|
0.3.7 | Sep 22, 2024 |
0.3.6 | Jun 9, 2024 |
0.3.4 | Mar 28, 2024 |
0.2.0 | Sep 15, 2022 |
#108 in Cargo plugins
454 downloads per month
125KB
3K
SLoC
cargo-sync-rdme
Cargo subcommand to synchronize README with the cargo manifest and crate documentation.
Installation
There are multiple ways to install cargo-sync-rdme. Choose any one of the methods below that best suits your needs.
Pre-built binaries
Executable binaries are available for download on the GitHub Release page.
Build from source using Rust
To build cargo-sync-rdme executable from the source, you must have the Rust toolchain installed. To install the rust toolchain, follow this guide.
Once you have installed Rust, the following command can be used to build and install cargo-sync-rdme:
# Install released version
$ cargo install cargo-sync-rdme
# Install latest version
$ cargo install --git https://github.com/gifnksm/cargo-sync-rdme.git cargo-sync-rdme
Usage
cargo-sync-rdme is a subcommand to synchronize the contents of README.md with the cargo manifest and crate documentation. By embedding marker comments in README.md, you can insert the documentation generated by cargo-sync-rdme. There are three types of marker comments as follows.
<!-- cargo-sync-rdme title -->
: generate document title (H1 element) from package name.<!-- cargo-sync-rdme badge -->
: generate badges from package metadata.<!-- cargo-sync-rdme rustdoc -->
: generate documentation for a crate from document comments.
Write the README.md as follows:
<!-- cargo-sync-rdme title -->
<!-- cargo-sync-rdme badge -->
<!-- cargo-sync-rdme rustdoc -->
To update the contents of README.md, run the following:
cargo sync-rdme --toolchain nightly
cargo-sync-rdme uses the unstable features of rustdoc, so nightly toolchain is required to generate READMEs from comments in the crate documentation. If nightly toolchain is not installed, it can be installed with the following command
rustup toolchain install nightly
The contents of README.md will be updated as follows:
<!-- cargo-sync-rdme title [[ -->
# (Package name)
<!-- cargo-sync-rdme ]] -->
<!-- cargo-sync-rdme badge [[ -->
(Badges)
<!-- cargo-sync-rdme ]] -->
<!-- cargo-sync-rdme rustdoc [[ -->
(Crate documentation)
<!-- cargo-sync-rdme ]] -->
See examples/lib for actual examples.
Configuration
You can customize the behavior of cargo-sync-rdme by adding the following section to Cargo.toml
.
[package.metadata.cargo-sync-rdme.badges]
maintenance = true
license = true
[package.metadata.cargo-sync-rdme.rustdoc]
html-root-url = "https://gifnksm.github.io/cargo-sync-rdme/"
See Configuration for details.
Minimum supported Rust version (MSRV)
The minimum supported Rust version is Rust 1.74.0. At least the last 3 versions of stable Rust are supported at any given time.
While a crate is a pre-release status (0.x.x) it may have its MSRV bumped in a patch release. Once a crate has reached 1.x, any MSRV bump will be accompanied by a new minor version.
License
This project is licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
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.
See CONTRIBUTING.md.
Dependencies
~16–30MB
~474K SLoC