From 358cccf9af0dd0a149b66e2a46bfa3f7e3137fa6 Mon Sep 17 00:00:00 2001 From: Yuri Astrakhan Date: Thu, 16 Dec 2021 23:40:33 -0500 Subject: [PATCH] [docs] Add output to all examples When viewing examples, it is very hard to figure out what they do without running them, which requires substantial efforts. I have added the output of all examples at the top. Also, two tiny spelling mistakes - in the readme and in the rename_all. In case anyone wants to auto-generate something similar, I used this helper script, and made a few minor line manipulations afterwards. ```bash run() { RES=$(cargo run -q --example "$1" -- --help 2> /dev/null | sed -e 's#^#//! #' ) { echo "//! Running this example with --help prints this message:" ; echo "//! -----------------------------------------------------" ; echo "$RES" ; echo "//! -----------------------------------------------------" ; echo "" ; cat "examples/$1.rs" ; } > "$1.rs" rm "examples/$1.rs" mv "$1.rs" "examples/" } run after_help run at_least_two ``` --- examples/README.md | 2 +- examples/after_help.rs | 24 ++++++++++++++ examples/at_least_two.rs | 15 +++++++++ examples/basic.rs | 24 ++++++++++++++ examples/deny_missing_docs.rs | 20 ++++++++++++ examples/doc_comments.rs | 50 +++++++++++++++++++++++++++++ examples/enum_in_args.rs | 15 +++++++++ examples/enum_in_args_with_strum.rs | 15 +++++++++ examples/enum_tuple.rs | 16 +++++++++ examples/env.rs | 17 ++++++++++ examples/example.rs | 23 +++++++++++++ examples/flatten.rs | 17 ++++++++++ examples/gen_completions.rs | 14 ++++++++ examples/git.rs | 18 +++++++++++ examples/group.rs | 20 ++++++++++++ examples/keyvalue.rs | 15 +++++++++ examples/negative_flag.rs | 13 ++++++++ examples/no_version.rs | 11 +++++++ examples/rename_all.rs | 19 ++++++++++- examples/required_if.rs | 19 +++++++++++ examples/subcommand_aliases.rs | 17 ++++++++++ 21 files changed, 382 insertions(+), 2 deletions(-) diff --git a/examples/README.md b/examples/README.md index b4853936..1475e2a9 100644 --- a/examples/README.md +++ b/examples/README.md @@ -31,7 +31,7 @@ How to extract subcommands' args into external structs. ### [Environment variables](env.rs) -How to use environment variable fallback an how it interacts with `default_value`. +How to use environment variable fallback and how it interacts with `default_value`. ### [Advanced](example.rs) diff --git a/examples/after_help.rs b/examples/after_help.rs index db2845fe..75816c74 100644 --- a/examples/after_help.rs +++ b/examples/after_help.rs @@ -1,4 +1,28 @@ //! How to append a postscript to the help message generated. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! structopt 0.3.25 +//! I am a program and I do things. +//! +//! Sometimes they even work. +//! +//! USAGE: +//! after_help [FLAGS] +//! +//! FLAGS: +//! -d +//! Release the dragon +//! +//! -h, --help +//! Prints help information +//! +//! -V, --version +//! Prints version information +//! +//! +//! Beware `-d`, dragons be here +//! ----------------------------------------------------- use structopt::StructOpt; diff --git a/examples/at_least_two.rs b/examples/at_least_two.rs index 683db503..a4eb0028 100644 --- a/examples/at_least_two.rs +++ b/examples/at_least_two.rs @@ -1,5 +1,20 @@ //! How to require presence of at least N values, //! like `val1 val2 ... valN ... valM`. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! structopt 0.3.25 +//! +//! USAGE: +//! at_least_two ... +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! +//! ARGS: +//! ... +//! ----------------------------------------------------- use structopt::StructOpt; diff --git a/examples/basic.rs b/examples/basic.rs index 510e0e0f..33e44155 100644 --- a/examples/basic.rs +++ b/examples/basic.rs @@ -1,4 +1,28 @@ //! A somewhat comprehensive example of a typical `StructOpt` usage.use +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! basic 0.3.25 +//! A basic example +//! +//! USAGE: +//! basic [FLAGS] [OPTIONS] --output [--] [FILE]... +//! +//! FLAGS: +//! -d, --debug Activate debug mode +//! -h, --help Prints help information +//! -V, --version Prints version information +//! -v, --verbose Verbose mode (-v, -vv, -vvv, etc.) +//! +//! OPTIONS: +//! -l, --level ... admin_level to consider +//! -c, --nb-cars Number of cars +//! -o, --output Output file +//! -s, --speed Set speed [default: 42] +//! +//! ARGS: +//! ... Files to process +//! ----------------------------------------------------- use std::path::PathBuf; use structopt::StructOpt; diff --git a/examples/deny_missing_docs.rs b/examples/deny_missing_docs.rs index 82b1e635..05ceca9d 100644 --- a/examples/deny_missing_docs.rs +++ b/examples/deny_missing_docs.rs @@ -10,6 +10,26 @@ // https://github.com/rust-lang/rust/issues/24584 is fixed //! A test to check that structopt compiles with deny(missing_docs) +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! structopt 0.3.25 +//! Some subcommands +//! +//! USAGE: +//! deny_missing_docs [FLAGS] [SUBCOMMAND] +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! -v +//! +//! SUBCOMMANDS: +//! a command A +//! b command B +//! c command C +//! help Prints this message or the help of the given subcommand(s) +//! ----------------------------------------------------- #![deny(missing_docs)] diff --git a/examples/doc_comments.rs b/examples/doc_comments.rs index 810101f6..3d221529 100644 --- a/examples/doc_comments.rs +++ b/examples/doc_comments.rs @@ -1,4 +1,54 @@ //! How to use doc comments in place of `help/long_help`. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! basic 0.3.25 +//! A basic example for the usage of doc comments as replacement of the arguments `help`, `long_help`, `about` and +//! `long_about` +//! +//! USAGE: +//! doc_comments [FLAGS] +//! +//! FLAGS: +//! -f, --first-flag +//! Just use doc comments to replace `help`, `long_help`, `about` or `long_about` input +//! +//! -h, --help +//! Prints help information +//! +//! -s, --second-flag +//! Split between `help` and `long_help`. +//! +//! In the previous case structopt is going to present the whole comment both as text for the `help` and the +//! `long_help` argument. +//! +//! But if the doc comment is formatted like this example -- with an empty second line splitting the heading and +//! the rest of the comment -- only the first line is used as `help` argument. The `long_help` argument will +//! still contain the whole comment. +//! +//! ## Attention +//! +//! Any formatting next to empty lines that could be used inside a doc comment is currently not preserved. If +//! lists or other well formatted content is required it is necessary to use the related structopt argument with +//! a raw string as shown on the `third_flag` description. +//! -t, --third-flag +//! This is a raw string. +//! +//! It can be used to pass well formatted content (e.g. lists or source +//! code) in the description: +//! +//! - first example list entry +//! - second example list entry +//! +//! -V, --version +//! Prints version information +//! +//! +//! SUBCOMMANDS: +//! first The same rules described previously for flags. Are also true for in regards of sub-commands +//! help Prints this message or the help of the given subcommand(s) +//! second Applicable for both `about` an `help` +//! ----------------------------------------------------- use structopt::StructOpt; diff --git a/examples/enum_in_args.rs b/examples/enum_in_args.rs index 70347da7..0722140d 100644 --- a/examples/enum_in_args.rs +++ b/examples/enum_in_args.rs @@ -1,4 +1,19 @@ //! How to use `arg_enum!` with `StructOpt`. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! structopt 0.3.25 +//! +//! USAGE: +//! enum_in_args +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! +//! ARGS: +//! Important argument [possible values: Foo, Bar, FooBar] +//! ----------------------------------------------------- use clap::arg_enum; use structopt::StructOpt; diff --git a/examples/enum_in_args_with_strum.rs b/examples/enum_in_args_with_strum.rs index a045a489..7893e78e 100644 --- a/examples/enum_in_args_with_strum.rs +++ b/examples/enum_in_args_with_strum.rs @@ -1,3 +1,18 @@ +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! structopt 0.3.25 +//! +//! USAGE: +//! enum_in_args_with_strum [OPTIONS] +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! +//! OPTIONS: +//! --format [default: txt] [possible values: txt, md, html] +//! ----------------------------------------------------- + use structopt::StructOpt; use strum::{EnumString, EnumVariantNames, VariantNames}; diff --git a/examples/enum_tuple.rs b/examples/enum_tuple.rs index 0bad2e64..a88adc2e 100644 --- a/examples/enum_tuple.rs +++ b/examples/enum_tuple.rs @@ -1,4 +1,20 @@ //! How to extract subcommands' args into external structs. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! classify 0.3.25 +//! +//! USAGE: +//! enum_tuple +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! +//! SUBCOMMANDS: +//! foo +//! help Prints this message or the help of the given subcommand(s) +//! ----------------------------------------------------- use structopt::StructOpt; diff --git a/examples/env.rs b/examples/env.rs index 04770894..437f3c68 100644 --- a/examples/env.rs +++ b/examples/env.rs @@ -1,5 +1,22 @@ //! How to use environment variable fallback an how it //! interacts with `default_value`. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! env 0.3.25 +//! Example for allowing to specify options via environment variables +//! +//! USAGE: +//! env [OPTIONS] --api-url +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! +//! OPTIONS: +//! --api-url URL for the API server [env: API_URL=] +//! --retries Number of retries [env: RETRIES=] [default: 5] +//! ----------------------------------------------------- use structopt::StructOpt; diff --git a/examples/example.rs b/examples/example.rs index 71cc1242..4dfd3412 100644 --- a/examples/example.rs +++ b/examples/example.rs @@ -1,4 +1,27 @@ //! Somewhat complex example of usage of structopt. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! example 0.3.25 +//! An example of StructOpt usage +//! +//! USAGE: +//! example [FLAGS] [OPTIONS] [--] [output] +//! +//! FLAGS: +//! -d, --debug Activate debug mode +//! -h, --help Prints help information +//! -V, --version Prints version information +//! +//! OPTIONS: +//! --log Log file, stdout if no file, no logging if not present +//! --optv ... +//! -s, --speed Set speed [default: 42] +//! +//! ARGS: +//! Input file +//! Output file, stdout if not present +//! ----------------------------------------------------- use structopt::StructOpt; diff --git a/examples/flatten.rs b/examples/flatten.rs index d51647f9..19208ec2 100644 --- a/examples/flatten.rs +++ b/examples/flatten.rs @@ -1,4 +1,21 @@ //! How to use flattening. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! structopt 0.3.25 +//! +//! USAGE: +//! flatten [FLAGS] -g -u +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! -v switch verbosity on +//! +//! OPTIONS: +//! -g daemon group +//! -u daemon user +//! ----------------------------------------------------- use structopt::StructOpt; diff --git a/examples/gen_completions.rs b/examples/gen_completions.rs index 4f35b075..8e4326f2 100644 --- a/examples/gen_completions.rs +++ b/examples/gen_completions.rs @@ -6,6 +6,20 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! structopt 0.3.25 +//! An example of how to generate bash completions with structopt +//! +//! USAGE: +//! gen_completions [FLAGS] +//! +//! FLAGS: +//! -d, --debug Activate debug mode +//! -h, --help Prints help information +//! -V, --version Prints version information +//! ----------------------------------------------------- + use structopt::clap::Shell; use structopt::StructOpt; diff --git a/examples/git.rs b/examples/git.rs index 494e9d1f..6e4137bd 100644 --- a/examples/git.rs +++ b/examples/git.rs @@ -2,6 +2,24 @@ //! as well as a demonstration of adding documentation to subcommands. //! Documentation can be added either through doc comments or //! `help`/`about` attributes. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! git 0.3.25 +//! the stupid content tracker +//! +//! USAGE: +//! git +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! +//! SUBCOMMANDS: +//! add +//! fetch fetch branches from remote repository +//! help Prints this message or the help of the given subcommand(s) +//! ----------------------------------------------------- use structopt::StructOpt; diff --git a/examples/group.rs b/examples/group.rs index d53de6a7..16ca3665 100644 --- a/examples/group.rs +++ b/examples/group.rs @@ -1,4 +1,24 @@ //! How to use `clap::Arg::group` +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! structopt 0.3.25 +//! +//! USAGE: +//! group [OPTIONS] <--method |--get|--head|--post|--put|--delete> +//! +//! FLAGS: +//! --delete HTTP DELETE +//! --get HTTP GET +//! -h, --help Prints help information +//! --head HTTP HEAD +//! --post HTTP POST +//! --put HTTP PUT +//! -V, --version Prints version information +//! +//! OPTIONS: +//! --method Set a custom HTTP verb +//! ----------------------------------------------------- use structopt::{clap::ArgGroup, StructOpt}; diff --git a/examples/keyvalue.rs b/examples/keyvalue.rs index 12ce6fc8..92acafaa 100644 --- a/examples/keyvalue.rs +++ b/examples/keyvalue.rs @@ -1,4 +1,19 @@ //! How to parse "key=value" pairs with structopt. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! structopt 0.3.25 +//! +//! USAGE: +//! keyvalue [OPTIONS] +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! +//! OPTIONS: +//! -D ... +//! ----------------------------------------------------- use std::error::Error; use structopt::StructOpt; diff --git a/examples/negative_flag.rs b/examples/negative_flag.rs index b178bf5a..0d9337c8 100644 --- a/examples/negative_flag.rs +++ b/examples/negative_flag.rs @@ -1,5 +1,18 @@ //! How to add `no-thing` flag which is `true` by default and //! `false` if passed. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! structopt 0.3.25 +//! +//! USAGE: +//! negative_flag [FLAGS] +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! --no-verbose +//! ----------------------------------------------------- use structopt::StructOpt; diff --git a/examples/no_version.rs b/examples/no_version.rs index a542ec1e..5fc6274e 100644 --- a/examples/no_version.rs +++ b/examples/no_version.rs @@ -1,4 +1,15 @@ //! How to completely remove version. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! no_version +//! +//! USAGE: +//! no_version +//! +//! FLAGS: +//! -h, --help Prints help information +//! ----------------------------------------------------- use structopt::clap::AppSettings; use structopt::StructOpt; diff --git a/examples/rename_all.rs b/examples/rename_all.rs index c7c3538a..6958c016 100644 --- a/examples/rename_all.rs +++ b/examples/rename_all.rs @@ -20,7 +20,24 @@ //! //! - **Lower Case**: Keep all letters lowercase and remove word boundaries. //! -//! - **Upper Case**: Keep all letters upperrcase and remove word boundaries. +//! - **Upper Case**: Keep all letters uppercase and remove word boundaries. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! rename_all 0.3.25 +//! +//! USAGE: +//! rename_all +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! +//! SUBCOMMANDS: +//! FIRST_COMMAND A screaming loud first command. Only use if necessary +//! SecondCommand Not nearly as loud as the first command +//! help Prints this message or the help of the given subcommand(s) +//! ----------------------------------------------------- use structopt::StructOpt; diff --git a/examples/required_if.rs b/examples/required_if.rs index cb6b414e..e3497b27 100644 --- a/examples/required_if.rs +++ b/examples/required_if.rs @@ -1,4 +1,23 @@ //! How to use `required_if` with structopt. +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! structopt 0.3.25 +//! +//! USAGE: +//! required_if -o [FILE] +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! +//! OPTIONS: +//! -o Where to write the output: to `stdout` or `file` +//! +//! ARGS: +//! File name: only required when `out-type` is set to `file` +//! ----------------------------------------------------- + use structopt::StructOpt; #[derive(Debug, StructOpt, PartialEq)] diff --git a/examples/subcommand_aliases.rs b/examples/subcommand_aliases.rs index 30b8cc37..1837ddbf 100644 --- a/examples/subcommand_aliases.rs +++ b/examples/subcommand_aliases.rs @@ -1,4 +1,21 @@ //! How to assign some aliases to subcommands +//! +//! Running this example with --help prints this message: +//! ----------------------------------------------------- +//! structopt 0.3.25 +//! +//! USAGE: +//! subcommand_aliases +//! +//! FLAGS: +//! -h, --help Prints help information +//! -V, --version Prints version information +//! +//! SUBCOMMANDS: +//! bar +//! foo +//! help Prints this message or the help of the given subcommand(s) +//! ----------------------------------------------------- use structopt::clap::AppSettings; use structopt::StructOpt;