cargo_readme/
lib.rs

1//! Generate README.md from doc comments.
2//!
3//! Cargo subcommand that extract documentation from your crate's doc comments that you can use to
4//! populate your README.md.
5//!
6//! ### Attribution
7//!
8//! This library was authored by Livio Ribeiro ([@livioribeiro](https://github.com/livioribeiro))
9//! and originally located at `https://github.com/livioribeiro/cargo-readme`, which now redirects
10//! here (as of August 2023). Thank you, Livio, for this lib!
11//!
12//! # Installation
13//!
14//! ```sh
15//! cargo install cargo-readme
16//! ```
17//!
18//! # Motivation
19//!
20//! As you write documentation, you often have to show examples of how to use your software. But
21//! how do you make sure your examples are all working properly? That we didn't forget to update
22//! them after a breaking change and left our (possibly new) users with errors they will have to
23//! figure out by themselves?
24//!
25//! With `cargo-readme`, you just write the rustdoc, run the tests, and then run:
26//!
27//! ```sh
28//! cargo readme > README.md
29//! ```
30//!
31//! And that's it! Your `README.md` is populated with the contents of the doc comments from your
32//! `lib.rs` (or `main.rs`).
33//!
34//! # Usage
35//!
36//! Let's take the following rust doc:
37//!
38//! ```ignore
39//! //! This is my awesome crate
40//! //!
41//! //! Here goes some other description of what it is and what is does
42//! //!
43//! //! # Examples
44//! //! ```
45//! //! fn sum2(n1: i32, n2: i32) -> i32 {
46//! //!   n1 + n2
47//! //! }
48//! //! # assert_eq!(4, sum2(2, 2));
49//! //! ```
50//! ```
51//!
52//! Running `cargo readme` will output the following:
53//!
54//! ~~~markdown
55//! [![Build Status](__badge_image__)](__badge_url__)
56//!
57//! # my_crate
58//!
59//! This is my awesome crate
60//!
61//! Here goes some other description of what it is and what is does
62//!
63//! ## Examples
64//! ```rust
65//! fn sum2(n1: i32, n2: i32) -> i32 {
66//!   n1 + n2
67//! }
68//! ```
69//!
70//! License: MY_LICENSE
71//! ~~~
72//!
73//! Let's see what's happened:
74//!
75//! - a badge was created from the one defined in the `[badges]` section of `Cargo.toml`
76//! - the crate name ("my-crate") was added
77//! - "# Examples" heading became "## Examples"
78//! - code block became "```rust"
79//! - hidden line `# assert_eq!(4, sum2(2, 2));` was removed
80//!
81//! `cargo-readme` also supports multiline doc comments `/*! */` (but you cannot mix styles):
82//!
83//! ~~~ignore
84//! /*!
85//! This is my awesome crate
86//!
87//! Here goes some other description of what it is and what is does
88//!
89//! # Examples
90//! ```
91//! fn sum2(n1: i32, n2: i32) -> i32 {
92//!   n1 + n2
93//! }
94//! # assert_eq!(4, sum2(2, 2));
95//! ```
96//! */
97//! ~~~
98//!
99//! If you have additional information that does not fit in doc comments, you can use a template.
100//! Just create a file called `README.tpl` in the same directory as `Cargo.toml` with the following
101//! content:
102//!
103//! ```tpl
104//! {{badges}}
105//!
106//! # {{crate}}
107//!
108//! {{readme}}
109//!
110//! Current version: {{version}}
111//!
112//! Some additional info here
113//!
114//! License: {{license}}
115//! ```
116//!
117//! The output will look like this
118//!
119//! ~~~markdown
120//! [![Build Status](__badge_image__)](__badge_url__)
121//!
122//! # my_crate
123//!
124//! Current version: 3.0.0
125//!
126//! This is my awesome crate
127//!
128//! Here goes some other description of what it is and what is does
129//!
130//! ## Examples
131//! ```rust
132//! fn sum2(n1: i32, n2: i32) -> i32 {
133//!   n1 + n2
134//! }
135//! ```
136//!
137//! Some additional info here
138//!
139//! License: MY_LICENSE
140//! ~~~
141//!
142//! By default, `README.tpl` will be used as the template, but you can override it using the
143//! `--template` to choose a different template or `--no-template` to disable it.
144
145mod config;
146mod readme;
147
148pub use config::get_manifest;
149pub use config::project;
150pub use readme::generate_readme;