Merge branch 'master' of https://github.com/rust-lang/mdBook into embed-svg

Author: notriddle

guide/src/cli/init.md

@@ -52,3 +52,19 @@ directory called `theme` in your source directory so that you can modify it.
 
 The theme is selectively overwritten, this means that if you don't want to
 overwrite a specific file, just delete it and the default file will be used.
+
+#### --title
+
+Specify a title for the book. If not supplied, an interactive prompt will ask for 
+a title. 
+
+```bash
+mdbook init --title="my amazing book"
+```
+
+#### --ignore
+
+Create a `.gitignore` file configured to ignore the `book` directory created when [building] a book. 
+If not supplied, an interactive prompt will ask whether it should be created.
+
+[building]: build.md

guide/src/cli/test.md

@@ -43,7 +43,17 @@ mdbook test path/to/book
 The `--library-path` (`-L`) option allows you to add directories to the library
 search path used by `rustdoc` when it builds and tests the examples. Multiple
 directories can be specified with multiple options (`-L foo -L bar`) or with a
-comma-delimited list (`-L foo,bar`).
+comma-delimited list (`-L foo,bar`). The path should point to the Cargo 
+[build cache](https://doc.rust-lang.org/cargo/guide/build-cache.html) `deps` directory that
+contains the build output of your project. For example, if your Rust project's book is in a directory
+named `my-book`, the following command would include the crate's dependencies when running `test`:
+
+```shell
+mdbook test my-book -L target/debug/deps/
+```
+
+See the `rustdoc` command-line [documentation](https://doc.rust-lang.org/rustdoc/command-line-arguments.html#-l--library-path-where-to-look-for-dependencies)
+for more information.
 
 #### --dest-dir
 

guide/src/continuous-integration.md

@@ -26,7 +26,7 @@ before_script:
   - cargo install-update -a
 
 script:
-  - mdbook build path/to/mybook && mdbook test path/to/mybook
+  - mdbook build && mdbook test # In case of custom book path: mdbook build path/to/mybook && mdbook test path/to/mybook
 ```
 
 ## Deploying Your Book to GitHub Pages
@@ -50,10 +50,10 @@ deploy:
   provider: pages
   skip-cleanup: true
   github-token: $GITHUB_TOKEN
-  local-dir: path/to/mybook/book
+  local-dir: book # In case of custom book path: path/to/mybook/book
   keep-history: false
   on:
-    branch: master
+    branch: main
 ```
 
 That's it!
@@ -77,18 +77,18 @@ before_script:
   - cargo install-update -a
 
 script:
-  - mdbook build path/to/mybook && mdbook test path/to/mybook
+  - mdbook build && mdbook test # In case of custom book path: mdbook build path/to/mybook && mdbook test path/to/mybook
   
 deploy:
   provider: pages
   strategy: git
   edge: true
   cleanup: false
   github-token: $GITHUB_TOKEN
-  local-dir: path/to/mybook/book
+  local-dir: book # In case of custom book path: path/to/mybook/book
   keep-history: false
   on:
-    branch: master
+    branch: main
   target_branch: gh-pages
 ```
 

guide/src/format/configuration/general.md

@@ -63,8 +63,8 @@ Options for the Rust language, relevant to running tests and playground
 integration.
 
 - **edition**: Rust edition to use by default for the code snippets. Default
-  is "2015". Individual code blocks can be controlled with the `edition2015`
-  or `edition2018` annotations, such as:
+  is "2015". Individual code blocks can be controlled with the `edition2015`, 
+  `edition2018` or `edition2021` annotations, such as:
 
   ~~~text
   ```rust,edition2015

guide/src/format/configuration/renderers.md

@@ -188,13 +188,13 @@ Enable it by adding an empty table to your `book.toml` as follows:
 There are no configuration options for the Markdown renderer at this time;
 only whether it is enabled or disabled.
 
-See [the preprocessors documentation](#configuring-preprocessors) for how to
+See [the preprocessors documentation](preprocessors.md) for how to
 specify which preprocessors should run before the Markdown renderer.
 
 ### Custom Renderers
 
 A custom renderer can be enabled by adding a `[output.foo]` table to your
-`book.toml`. Similar to [preprocessors](#configuring-preprocessors) this will
+`book.toml`. Similar to [preprocessors](preprocessors.md) this will
 instruct `mdbook` to pass a representation of the book to `mdbook-foo` for
 rendering. See the [alternative backends] chapter for more detail.
 

guide/src/format/mdbook.md

@@ -21,7 +21,7 @@ Will render as
 ```rust
 # fn main() {
     let x = 5;
-    let y = 7;
+    let y = 6;
 
     println!("{}", x + y);
 # }

src/book/mod.rs

@@ -274,6 +274,10 @@ impl MDBook {
                         RustEdition::E2018 => {
                             cmd.args(&["--edition", "2018"]);
                         }
+                        RustEdition::E2021 => {
+                            cmd.args(&["--edition", "2021"])
+                                .args(&["-Z", "unstable-options"]);
+                        }
                     }
                 }
 

src/cmd/init.rs

@@ -1,5 +1,5 @@
 use crate::get_book_dir;
-use clap::{App, ArgMatches, SubCommand};
+use clap::{App, Arg, ArgMatches, SubCommand};
 use mdbook::config;
 use mdbook::errors::Result;
 use mdbook::MDBook;
@@ -18,14 +18,28 @@ pub fn make_subcommand<'a, 'b>() -> App<'a, 'b> {
         )
         .arg_from_usage("--theme 'Copies the default theme into your source folder'")
         .arg_from_usage("--force 'Skips confirmation prompts'")
+        .arg(
+            Arg::with_name("title")
+                .long("title")
+                .takes_value(true)
+                .help("Sets the book title")
+                .required(false),
+        )
+        .arg(
+            Arg::with_name("ignore")
+                .long("ignore")
+                .takes_value(true)
+                .possible_values(&["none", "git"])
+                .help("Creates a VCS ignore file (i.e. .gitignore)")
+                .required(false),
+        )
 }
 
 // Init command implementation
 pub fn execute(args: &ArgMatches) -> Result<()> {
     let book_dir = get_book_dir(args);
     let mut builder = MDBook::init(&book_dir);
     let mut config = config::Config::default();
-
     // If flag `--theme` is present, copy theme to src
     if args.is_present("theme") {
         let theme_dir = book_dir.join("theme");
@@ -45,13 +59,23 @@ pub fn execute(args: &ArgMatches) -> Result<()> {
         }
     }
 
-    println!("\nDo you want a .gitignore to be created? (y/n)");
-
-    if confirm() {
-        builder.create_gitignore(true);
+    if let Some(ignore) = args.value_of("ignore") {
+        match ignore {
+            "git" => builder.create_gitignore(true),
+            _ => builder.create_gitignore(false),
+        };
+    } else {
+        println!("\nDo you want a .gitignore to be created? (y/n)");
+        if confirm() {
+            builder.create_gitignore(true);
+        }
     }
 
-    config.book.title = request_book_title();
+    config.book.title = if args.is_present("title") {
+        args.value_of("title").map(String::from)
+    } else {
+        request_book_title()
+    };
 
     if let Some(author) = get_author_name() {
         debug!("Obtained user name from gitconfig: {:?}", author);

src/config.rs

@@ -467,6 +467,9 @@ pub struct RustConfig {
 #[derive(Debug, Copy, Clone, PartialEq, Serialize, Deserialize)]
 /// Rust edition to use for the code.
 pub enum RustEdition {
+    /// The 2021 edition of Rust
+    #[serde(rename = "2021")]
+    E2021,
     /// The 2018 edition of Rust
     #[serde(rename = "2018")]
     E2018,
@@ -855,6 +858,26 @@ mod tests {
         assert_eq!(got.rust, rust_should_be);
     }
 
+    #[test]
+    fn edition_2021() {
+        let src = r#"
+        [book]
+        title = "mdBook Documentation"
+        description = "Create book from markdown files. Like Gitbook but implemented in Rust"
+        authors = ["Mathieu David"]
+        src = "./source"
+        [rust]
+        edition = "2021"
+        "#;
+
+        let rust_should_be = RustConfig {
+            edition: Some(RustEdition::E2021),
+        };
+
+        let got = Config::from_str(src).unwrap();
+        assert_eq!(got.rust, rust_should_be);
+    }
+
     #[test]
     fn load_arbitrary_output_type() {
         #[derive(Debug, Deserialize, PartialEq)]

src/main.rs

@@ -3,8 +3,9 @@ extern crate clap;
 #[macro_use]
 extern crate log;
 
+use anyhow::anyhow;
 use chrono::Local;
-use clap::{App, AppSettings, ArgMatches};
+use clap::{App, AppSettings, Arg, ArgMatches, Shell, SubCommand};
 use env_logger::Builder;
 use log::LevelFilter;
 use mdbook::utils;
@@ -20,7 +21,40 @@ const VERSION: &str = concat!("v", crate_version!());
 fn main() {
     init_logger();
 
-    // Create a list of valid arguments and sub-commands
+    let app = create_clap_app();
+
+    // Check which subcomamnd the user ran...
+    let res = match app.get_matches().subcommand() {
+        ("init", Some(sub_matches)) => cmd::init::execute(sub_matches),
+        ("build", Some(sub_matches)) => cmd::build::execute(sub_matches),
+        ("clean", Some(sub_matches)) => cmd::clean::execute(sub_matches),
+        #[cfg(feature = "watch")]
+        ("watch", Some(sub_matches)) => cmd::watch::execute(sub_matches),
+        #[cfg(feature = "serve")]
+        ("serve", Some(sub_matches)) => cmd::serve::execute(sub_matches),
+        ("test", Some(sub_matches)) => cmd::test::execute(sub_matches),
+        ("completions", Some(sub_matches)) => (|| {
+            let shell: Shell = sub_matches
+                .value_of("shell")
+                .ok_or_else(|| anyhow!("Shell name missing."))?
+                .parse()
+                .map_err(|s| anyhow!("Invalid shell: {}", s))?;
+
+            create_clap_app().gen_completions_to("mdbook", shell, &mut std::io::stdout().lock());
+            Ok(())
+        })(),
+        (_, _) => unreachable!(),
+    };
+
+    if let Err(e) = res {
+        utils::log_backtrace(&e);
+
+        std::process::exit(101);
+    }
+}
+
+/// Create a list of valid arguments and sub-commands
+fn create_clap_app<'a, 'b>() -> App<'a, 'b> {
     let app = App::new(crate_name!())
         .about(crate_description!())
         .author("Mathieu David <[email protected]>")
@@ -35,31 +69,26 @@ fn main() {
         .subcommand(cmd::init::make_subcommand())
         .subcommand(cmd::build::make_subcommand())
         .subcommand(cmd::test::make_subcommand())
-        .subcommand(cmd::clean::make_subcommand());
+        .subcommand(cmd::clean::make_subcommand())
+        .subcommand(
+            SubCommand::with_name("completions")
+                .about("Generate shell completions for your shell to stdout")
+                .arg(
+                    Arg::with_name("shell")
+                        .takes_value(true)
+                        .possible_values(&Shell::variants())
+                        .help("the shell to generate completions for")
+                        .value_name("SHELL")
+                        .required(true),
+                ),
+        );
 
     #[cfg(feature = "watch")]
     let app = app.subcommand(cmd::watch::make_subcommand());
     #[cfg(feature = "serve")]
     let app = app.subcommand(cmd::serve::make_subcommand());
 
-    // Check which subcomamnd the user ran...
-    let res = match app.get_matches().subcommand() {
-        ("init", Some(sub_matches)) => cmd::init::execute(sub_matches),
-        ("build", Some(sub_matches)) => cmd::build::execute(sub_matches),
-        ("clean", Some(sub_matches)) => cmd::clean::execute(sub_matches),
-        #[cfg(feature = "watch")]
-        ("watch", Some(sub_matches)) => cmd::watch::execute(sub_matches),
-        #[cfg(feature = "serve")]
-        ("serve", Some(sub_matches)) => cmd::serve::execute(sub_matches),
-        ("test", Some(sub_matches)) => cmd::test::execute(sub_matches),
-        (_, _) => unreachable!(),
-    };
-
-    if let Err(e) = res {
-        utils::log_backtrace(&e);
-
-        std::process::exit(101);
-    }
+    app
 }
 
 fn init_logger() {