Merge pull request #246 from pacak/docs

More docs

docs2/src/derive_basic_commands/cases.md

@@ -0,0 +1,10 @@
+Help message lists subcommand
+> --help
+
+Commands have their own arguments
+
+> run --name Bob
+
+> test
+
+> test --name bob

docs2/src/derive_basic_commands/derive.rs

@@ -0,0 +1,16 @@
+//
+use bpaf::*;
+#[derive(Debug, Clone, Bpaf)]
+#[bpaf(options)]
+pub enum Options {
+    #[bpaf(command("run"))]
+    /// Run a binary
+    Run {
+        /// Name of a binary crate
+        name: String,
+    },
+
+    /// Run a self test
+    #[bpaf(command)]
+    Test,
+}

docs2/src/derive_basic_custom_consumer/cases.md

@@ -0,0 +1,11 @@
+`bpaf` generates help message with a short name only as described
+
+> --help
+
+And accepts the short name only
+
+> -s 42
+
+long name is missing
+
+> --switch 42

docs2/src/derive_basic_custom_consumer/derive.rs

@@ -0,0 +1,13 @@
+//
+use bpaf::*;
+#[derive(Debug, Clone, Bpaf)]
+#[bpaf(options)]
+pub struct Options {
+    /// A custom switch
+    #[bpaf(short, switch)]
+    switch: bool,
+
+    /// Custom number
+    #[bpaf(positional("NUM"))]
+    argument: usize,
+}

docs2/src/derive_basic_custom_name/cases.md

@@ -0,0 +1,10 @@
+`bpaf` uses custom names in help message
+
+> --help
+
+As well as accepts them on a command line and uses in error message
+
+> --switch
+
+> -A 42 -s
+

docs2/src/derive_basic_custom_name/derive.rs

@@ -0,0 +1,13 @@
+//
+use bpaf::*;
+#[derive(Debug, Clone, Bpaf)]
+#[bpaf(options)]
+pub struct Options {
+    /// A custom switch
+    #[bpaf(short, long)]
+    switch: bool,
+
+    /// A custom argument
+    #[bpaf(long("my-argument"), short('A'))]
+    argument: usize,
+}

docs2/src/derive_basic_enum/cases.md

@@ -0,0 +1,18 @@
+Help message reflects mutually exclusive parts
+
+> --help
+
+At least one branch needs to succeed
+
+>
+
+And in this example only one branch can succeed
+
+> --name Cargo.toml
+
+> --url https://crates.io --auth-method digest
+
+While both branches can succeed at once - only one will actually succeed and afetr that
+parsing fails since there are unconsumed items
+
+> --url https://crates.io --auth-method digest --name Cargo.toml

docs2/src/derive_basic_enum/derive.rs

@@ -0,0 +1,17 @@
+//
+use bpaf::*;
+#[derive(Debug, Clone, Bpaf)]
+#[bpaf(options)]
+pub enum Options {
+    File {
+        /// Read input from a file
+        name: String,
+    },
+
+    Url {
+        /// Read input from URL
+        url: String,
+        /// Authentication method to use for the URL
+        auth_method: String,
+    },
+}

docs2/src/derive_basic_intro/cases.md

@@ -0,0 +1,12 @@
+bpaf generates a help message
+
+> --help
+
+And two parsers. Numeric argument is required, boolean switch is optional and fall back value
+is false.
+
+> --switch
+
+> --switch --argument 42
+
+> --argument 42

docs2/src/derive_basic_intro/derive.rs

@@ -0,0 +1,11 @@
+use bpaf::*;
+
+#[derive(Debug, Clone, Bpaf)]
+#[bpaf(options)]
+pub struct Options {
+    /// A custom switch
+    switch: bool,
+
+    /// A custom argument
+    argument: usize,
+}

docs2/src/derive_basic_nesting/cases.md

@@ -0,0 +1,10 @@
+Help message lists all possible options
+
+> --help
+
+Parser accepts one and only one value from enum in this example
+
+> --input Cargo.toml --html
+> --input Cargo.toml --manpage
+
+> --input hello

docs2/src/derive_basic_nesting/derive.rs

@@ -0,0 +1,20 @@
+//
+use bpaf::*;
+#[derive(Debug, Clone, Bpaf)]
+pub enum Format {
+    /// Produce output in HTML format
+    Html,
+    /// Produce output in Markdown format
+    Markdown,
+    /// Produce output in manpage format
+    Manpage,
+}
+
+#[derive(Debug, Clone, Bpaf)]
+#[bpaf(options)]
+pub struct Options {
+    /// File to process
+    input: String,
+    #[bpaf(external(format))]
+    format: Format,
+}

docs2/src/derive_basic_postpr/cases.md

@@ -0,0 +1,11 @@
+Help as usual
+
+> --help
+
+And parsed values are differnt from what user passes
+
+> --width 10 --height 3
+
+Additionally height cannot exceed 10
+
+> --width 555 --height 42

docs2/src/derive_basic_postpr/derive.rs

@@ -0,0 +1,17 @@
+//
+use bpaf::*;
+fn small(size: &usize) -> bool {
+    *size < 10
+}
+
+#[derive(Debug, Clone, Bpaf)]
+#[bpaf(options)]
+pub struct Options {
+    // double the width
+    #[bpaf(short, argument::<usize>("PX"), map(|w| w*2))]
+    width: usize,
+
+    // make sure the hight is below 10
+    #[bpaf(argument::<usize>("LENGTH"), guard(small, "must be less than 10"))]
+    height: usize,
+}

documentation/_documentation/_1_tutorials/_2_derive_api/_0_intro/index.md

@@ -2,24 +2,7 @@
 
 Let's take a look at a simple example
 
-```no_run
-use bpaf::*;
-
-#[derive(Debug, Clone, Bpaf)]
-#[bpaf(options)]
-pub struct Options {
-    /// A custom switch
-    switch: bool,
-
-    /// A custom argument
-    argument: usize,
-}
-
-fn main() {
-    let opts = options().run();
-    println!("{:?}", opts)
-}
-```
+#![cfg_attr(not(doctest), doc = include_str!("docs2/derive_basic_intro.md"))]
 
 `bpaf` is trying hard to guess what you are trying to achieve just from the types so it will
 pick up types, doc comment, presence or absence of names, but it is possible to customize all

documentation/_documentation/_1_tutorials/_2_derive_api/_1_custom_names/index.md

@@ -3,25 +3,7 @@
 By default names for flag names are taken directly from the field names so usually you don't
 have to do anything about it, but you can change it with annotations on the fields themselves:
 
-```no_run
-# use bpaf::*;
-#[derive(Debug, Clone, Bpaf)]
-#[bpaf(options)]
-pub struct Options {
-    /// A custom switch
-    #[bpaf(short, long)]
-    switch: bool,
-
-    /// A custom argument
-    #[bpaf(long("my-argument"), short('A'))]
-    argument: usize,
-}
-
-fn main() {
-    let opts = options().run();
-    println!("{:?}", opts);
-}
-```
+#![cfg_attr(not(doctest), doc = include_str!("docs2/derive_basic_custom_name.md"))]
 
 Rules for picking the name are:
 

documentation/_documentation/_1_tutorials/_2_derive_api/_2_custom_consumers/index.md

@@ -14,25 +14,7 @@ By default `bpaf` picks parsers depending on a field type according to those rul
 You can change it with annotations like `switch`, `argument` or `positional`
 
 
-```no_run
-# use bpaf::*;
-#[derive(Debug, Clone, Bpaf)]
-#[bpaf(options)]
-pub struct Options {
-    /// A custom switch
-    #[bpaf(short, switch)]
-    switch: bool,
-
-    /// A custom argument
-    #[bpaf(positional("NAME"))]
-    argument: usize,
-}
-
-fn main() {
-    let opts = options().run();
-    println!("{:?}", opts);
-}
-```
+#![cfg_attr(not(doctest), doc = include_str!("docs2/derive_basic_custom_consumer.md"))]
 
 With arguments that consume a value you can specify its type using turbofish-line syntax
 

documentation/_documentation/_1_tutorials/_2_derive_api/_3_postpr/index.md

@@ -1,28 +1,8 @@
-#### Applying transformations to parsed values
+#### Transforming parsed values
 
 Once field have a consumer you can start applying transformations from [`Parser`] trait.
 Annotation share the same names and follow the same composition rules as in Combinatoric API.
 
-```no_run
-# use bpaf::*;
-fn small(size: &usize) -> bool {
-    *size < 10
-}
 
-#[derive(Debug, Clone, Bpaf)]
-#[bpaf(options)]
-pub struct Options {
-    // double the width
-    #[bpaf(short, argument::<usize>("PX"), map(|w| w*2))]
-    width: usize,
+#![cfg_attr(not(doctest), doc = include_str!("docs2/derive_basic_postpr.md"))]
 
-    // make sure the hight is below 10
-    #[bpaf(argument::<usize>("LENGTH"), guard(small, "must be less than 10"))]
-    height: usize,
-}
-
-fn main() {
-    let opts = options().run();
-    println!("{:?}", opts);
-}
-```

documentation/_documentation/_1_tutorials/_2_derive_api/_4_enums_and_structs/index.md

@@ -6,26 +6,4 @@ it for some other purpose as well and want to skip them during parsing you can u
 If you use `#[derive(Bpaf)]` on enum parser will produce variant for which all the parsers
 succeed.
 
-```no_run
-# use bpaf::*;
-#[derive(Debug, Clone, Bpaf)]
-#[bpaf(options)]
-pub enum Input {
-    File {
-        /// Read input from a file
-        name: String,
-    },
-
-    Url {
-        /// Read input from URL
-        url: String,
-        /// Authentication method to use for the URL
-        auth_method: String,
-    }
-}
-
-fn main() {
-    let opts = input().run();
-    println!("{:?}", opts);
-}
-```
+#![cfg_attr(not(doctest), doc = include_str!("docs2/derive_basic_enum.md"))]

documentation/_documentation/_1_tutorials/_2_derive_api/_6_nesting/index.md

@@ -4,34 +4,4 @@ Up to this point we've been looking at cases where fields of a structure are all
 parsers, possibly wrapped in `Option` or `Vec`, but it also possible to nest derived parsers
 too:
 
-```no_run
-# use bpaf::*;
-#[derive(Debug, Clone, Bpaf)]
-pub enum Format {
-    /// Produce output in HTML format
-    Html,
-    /// Produce output in Markdown format
-    Markdown,
-    /// Produce output in manpage format
-    Manpage
-}
-
-#[derive(Debug, Clone, Bpaf)]
-#[bpaf(options)]
-pub struct Options {
-    /// File to process
-    input: String,
-    #[bpaf(external(format))]
-    format: Format
-}
-
-fn main() {
-    let opts = options().run();
-    println!("{:?}", opts);
-}
-```
-
-`external` annotation replaces the consumer and parameter it takes is a function name created
-either manually with combinatoric API or derived with `#[derive(Bpaf)]`. If parameter is
-omitted then it would default to the field name. In example above since both function and field
-are called `format` - annotation `#[bpaf(external)]` would be sufficient.
+#![cfg_attr(not(doctest), doc = include_str!("docs2/derive_basic_nesting.md"))]