cargo-readme 3.4.0

//! Generate README.md from doc comments.
//!
//! Cargo subcommand that extract documentation from your crate's doc comments that you can use to
//! populate your README.md.
//!
//! ### Attribution
//!
//! This library was authored by Livio Ribeiro ([@livioribeiro](https://github.com/livioribeiro))
//! and originally located at `https://github.com/livioribeiro/cargo-readme`, which now redirects
//! here (as of August 2023). Thank you, Livio, for this lib!
//!
//! # Installation
//!
//! ```sh
//! cargo install cargo-readme
//! ```
//!
//! # Motivation
//!
//! As you write documentation, you often have to show examples of how to use your software. But
//! how do you make sure your examples are all working properly? That we didn't forget to update
//! them after a breaking change and left our (possibly new) users with errors they will have to
//! figure out by themselves?
//!
//! With `cargo-readme`, you just write the rustdoc, run the tests, and then run:
//!
//! ```sh
//! cargo readme -o README.md
//! ```
//!
//! And that's it! Your `README.md` is populated with the contents of the doc comments from your
//! `lib.rs` (or `main.rs`).
//!
//! # Usage
//!
//! Let's take the following rust doc:
//!
//! ```ignore
//! //! This is my awesome crate
//! //!
//! //! Here goes some other description of what it is and what is does
//! //!
//! //! # Examples
//! //! ```
//! //! fn sum2(n1: i32, n2: i32) -> i32 {
//! //!   n1 + n2
//! //! }
//! //! # assert_eq!(4, sum2(2, 2));
//! //! ```
//! ```
//!
//! Running `cargo readme` will output the following:
//!
//! ~~~markdown
//! [![Build Status](__badge_image__)](__badge_url__)
//!
//! # my_crate
//!
//! This is my awesome crate
//!
//! Here goes some other description of what it is and what is does
//!
//! ## Examples
//! ```rust
//! fn sum2(n1: i32, n2: i32) -> i32 {
//!   n1 + n2
//! }
//! ```
//!
//! License: MY_LICENSE
//! ~~~
//!
//! Let's see what's happened:
//!
//! - a badge was created from the one defined in the `[badges]` section of `Cargo.toml`
//! - the crate name ("my-crate") was added
//! - "# Examples" heading became "## Examples"
//! - code block became "```rust"
//! - hidden line `# assert_eq!(4, sum2(2, 2));` was removed
//!
//! `cargo-readme` also supports multiline doc comments `/*! */` (but you cannot mix styles):
//!
//! ~~~ignore
//! /*!
//! This is my awesome crate
//!
//! Here goes some other description of what it is and what is does
//!
//! # Examples
//! ```
//! fn sum2(n1: i32, n2: i32) -> i32 {
//!   n1 + n2
//! }
//! # assert_eq!(4, sum2(2, 2));
//! ```
//! */
//! ~~~
//!
//! If you have additional information that does not fit in doc comments, you can use a template.
//! Just create a file called `README.tpl` in the same directory as `Cargo.toml` with the following
//! content:
//!
//! ```tpl
//! {{badges}}
//!
//! # {{crate}}
//!
//! {{readme}}
//!
//! Current version: {{version}}
//!
//! Some additional info here
//!
//! License: {{license}}
//! ```
//!
//! The output will look like this
//!
//! ~~~markdown
//! [![Build Status](__badge_image__)](__badge_url__)
//!
//! # my_crate
//!
//! Current version: 3.0.0
//!
//! This is my awesome crate
//!
//! Here goes some other description of what it is and what is does
//!
//! ## Examples
//! ```rust
//! fn sum2(n1: i32, n2: i32) -> i32 {
//!   n1 + n2
//! }
//! ```
//!
//! Some additional info here
//!
//! License: MY_LICENSE
//! ~~~
//!
//! By default, `README.tpl` will be used as the template, but you can override it using the
//! `--template` to choose a different template or `--no-template` to disable it.
//!
//! # Badges
//!
//! `crates.io` no longer renders the `[badges]` section of `Cargo.toml` on the crate page, but it
//! does render your `README.md`. `cargo-readme` bridges the two: it turns each entry in `[badges]`
//! into a markdown badge prepended to the output (unless you pass `--no-badges`). The supported
//! keys and the attributes each one reads are:
//!
//! | Badge key | Required | Optional |
//! |---|---|---|
//! | `crates-io` *(extension)* | | `crate` (defaults to the package name) |
//! | `appveyor` | `repository` | `branch`, `service` |
//! | `circle-ci` | `repository` | `branch`, `service` |
//! | `gitlab` | `repository` | `branch` |
//! | `travis-ci` | `repository` | `branch` |
//! | `github` *(extension)* | `repository` | `workflow` |
//! | `codecov` | `repository` | `branch`, `service` |
//! | `coveralls` | `repository` | `branch`, `service` |
//! | `is-it-maintained-issue-resolution` | `repository` | |
//! | `is-it-maintained-open-issues` | `repository` | |
//! | `maintenance` | `status` | |
//!
//! `maintenance` is the only badge the [Cargo manifest reference][manifest] still documents; its
//! `status` accepts `actively-developed`, `passively-maintained`, `as-is`, `experimental`,
//! `looking-for-maintainer`, `deprecated`, and `none`. `github` and `crates-io` are `cargo-readme`
//! extensions. Run `cargo readme --list-badges` to print this list from your terminal.
//!
//! [manifest]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-badges-section
//!
//! # Reusing a Markdown file as documentation
//!
//! Rustdoc can pull a crate's documentation straight from a Markdown file:
//!
//! ```rust,ignore
//! #![doc = include_str!("README.rustdoc.md")]
//! ```
//!
//! Point `cargo readme` at that same file with `--no-comment-extraction` and it will process the
//! Markdown as-is instead of scanning for doc comments, so a single source produces both the
//! rendered crate docs and the repository `README.md`. Hidden doctest lines (starting with `# `)
//! are still stripped, so examples stay runnable in `cargo test` yet read cleanly on GitHub.

mod config;
mod readme;

pub use config::get_manifest;
pub use config::project;
pub use config::{supported_badges, BadgeInfo};
pub use readme::generate_readme;
pub use readme::ReadmeOptions;