1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153
//! 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. //! //! # 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 > 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. #[macro_use] extern crate serde_derive; #[macro_use] extern crate lazy_static; extern crate percent_encoding; extern crate regex; extern crate toml; mod config; mod readme; pub use config::get_manifest; pub use config::project; pub use readme::generate_readme;