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

//! 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 braking 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}}
//!
//! Some additional info here
//!
//! License: {{license}}
//! ```
//!
//! The output will look like this
//!
//! ~~~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
//! }
//! ```
//!
//! 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 regex;
extern crate toml;
extern crate percent_encoding;

mod readme;
mod config;

pub use readme::generate_readme;
pub use config::get_manifest;
pub use config::project;