Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(tutorial): Smooth over tutorial problems, a little #4985

Merged
merged 3 commits into from
Jun 23, 2023
Merged

docs(tutorial): Smooth over tutorial problems, a little #4985

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c2e6f1b
docs(derive): Draw more attention to derive feature
epage Jun 23, 2023
7370c63
docs(tutorial): Provide next steps
epage Jun 23, 2023
975eb0c
docs(tutorial): Link out to other docs more
epage Jun 23, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
59 changes: 40 additions & 19 deletions src/_derive/_tutorial.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
//! 3. [Argument Relations](#argument-relations)
//! 4. [Custom Validation](#custom-validation)
//! 5. [Testing](#testing)
//! 6. [Next Steps](#next-steps)
//!
//! See also
//! - [FAQ: When should I use the builder vs derive APIs?][crate::_faq#when-should-i-use-the-builder-vs-derive-apis]
Expand All @@ -31,7 +32,12 @@
//! ## Quick Start
//!
//! You can create an application declaratively with a `struct` and some
//! attributes. **This requires enabling the [`derive` feature flag][crate::_features].**
//! attributes.
//!
//! First, ensure `clap` is available with the [`derive` feature flag][crate::_features]:
//! ```console
//! $ cargo add clap --features derive
//! ```
//!
//! ```rust
#![doc = include_str!("../../examples/tutorial_derive/01_quick.rs")]
Expand All @@ -49,14 +55,14 @@
//!
#![doc = include_str!("../../examples/tutorial_derive/02_apps.md")]
//!
//! You can use `#[command(author, version, about)]` attribute defaults to fill these fields in from your `Cargo.toml` file.
//! You can use [`#[command(author, version, about)]` attribute defaults][super#command-attributes] to fill these fields in from your `Cargo.toml` file.
//!
//! ```rust
#![doc = include_str!("../../examples/tutorial_derive/02_crate.rs")]
//! ```
#![doc = include_str!("../../examples/tutorial_derive/02_crate.md")]
//!
//! You can use attributes to change the application level behavior of clap. Any [`Command`][crate::Command] builder function can be used as an attribute.
//! You can use attributes to change the application level behavior of clap. Any [`Command`][crate::Command] builder function can be used as an attribute, like [`Command::next_line_help`].
//!
//! ```rust
#![doc = include_str!("../../examples/tutorial_derive/02_app_settings.rs")]
Expand All @@ -74,8 +80,8 @@
//! ```
#![doc = include_str!("../../examples/tutorial_derive/03_03_positional.md")]
//!
//! Note that the default [`ArgAction`][crate::ArgAction] is [`Set`][crate::ArgAction::Set]. To
//! accept multiple values, use [`Append`][crate::ArgAction::Append] via `Vec`:
//! Note that the [default `ArgAction` is `Set`][super#arg-types]. To
//! accept multiple values, override the [action][Arg::action] with [`Append`][crate::ArgAction::Append] via `Vec`:
//! ```rust
#![doc = include_str!("../../examples/tutorial_derive/03_03_positional_mult.rs")]
//! ```
Expand All @@ -88,35 +94,33 @@
//! - They can be optional
//! - Intent is clearer
//!
//! The `#[arg(short = 'n')]` and `#[arg(long = "name")]` attributes that define
//! The [`#[arg(short = 'n')]`][Arg::short] and [`#[arg(long = "name")]`][Arg::long] attributes that define
//! the flags are [`Arg`][crate::Args] methods that are derived from the field name when no value
//! is specified (`#[arg(short)]` and `#[arg(long)]`).
//! is specified ([`#[arg(short)]` and `#[arg(long)]`][super#arg-attributes]).
//!
//! ```rust
#![doc = include_str!("../../examples/tutorial_derive/03_02_option.rs")]
//! ```
#![doc = include_str!("../../examples/tutorial_derive/03_02_option.md")]
//!
//! Note that the default [`ArgAction`][crate::ArgAction] is [`Set`][crate::ArgAction::Set]. To
//! accept multiple occurrences, use [`Append`][crate::ArgAction::Append] via `Vec`:
//! Note that the [default `ArgAction` is `Set`][super#arg-types]. To
//! accept multiple occurrences, override the [action][Arg::action] with [`Append`][crate::ArgAction::Append] via `Vec`:
//! ```rust
#![doc = include_str!("../../examples/tutorial_derive/03_02_option_mult.rs")]
//! ```
#![doc = include_str!("../../examples/tutorial_derive/03_02_option_mult.md")]
//!
//! ### Flags
//!
//! Flags can also be switches that can be on/off. This is enabled via the
//! `#[arg(action = ArgAction::SetTrue)]` attribute though this is implied when the field is a
//! `bool`.
//! Flags can also be switches that can be on/off:
//!
//! ```rust
#![doc = include_str!("../../examples/tutorial_derive/03_01_flag_bool.rs")]
//! ```
#![doc = include_str!("../../examples/tutorial_derive/03_01_flag_bool.md")]
//!
//! Note that the default [`ArgAction`][crate::ArgAction] for a `bool` field is
//! [`SetTrue`][crate::ArgAction::SetTrue]. To accept multiple flags, use
//! Note that the [default `ArgAction` for a `bool` field is
//! `SetTrue`][super#arg-types]. To accept multiple flags, override the [action][Arg::action] with
//! [`Count`][crate::ArgAction::Count]:
//!
//! ```rust
Expand All @@ -126,7 +130,7 @@
//!
//! ### Subcommands
//!
//! Subcommands are derived with `#[derive(Subcommand)]` and be added via `#[command(subcommand)]` attribute. Each
//! Subcommands are derived with `#[derive(Subcommand)]` and be added via [`#[command(subcommand)]` attribute][super#command-attributes]. Each
//! instance of a [Subcommand][crate::Subcommand] can have its own version, author(s), Args, and even its own
//! subcommands.
//!
Expand All @@ -145,7 +149,7 @@
//!
//! We've previously showed that arguments can be [`required`][crate::Arg::required] or optional.
//! When optional, you work with a `Option` and can `unwrap_or`. Alternatively, you can
//! set `#[arg(default_value_t)]`.
//! set [`#[arg(default_value_t)]`][super#arg-attributes].
//!
//! ```rust
#![doc = include_str!("../../examples/tutorial_derive/03_05_default_values.rs")]
Expand All @@ -160,7 +164,8 @@
//! ### Enumerated values
//!
//! For example, if you have arguments of specific values you want to test for, you can derive
//! [`ValueEnum`][crate::ValueEnum].
//! [`ValueEnum`][super#valueenum-attributes]
//! (any [`PossibleValue`] builder function can be used as variant attributes).
//!
//! This allows you specify the valid values for that argument. If the user does not use one of
//! those specific values, they will receive a graceful exit with error message informing them
Expand All @@ -173,14 +178,14 @@
//!
//! ### Validated values
//!
//! More generally, you can validate and parse into any data type.
//! More generally, you can validate and parse into any data type with [`Arg::value_parser`].
//!
//! ```rust
#![doc = include_str!("../../examples/tutorial_derive/04_02_parse.rs")]
//! ```
#![doc = include_str!("../../examples/tutorial_derive/04_02_parse.md")]
//!
//! A custom parser can be used to improve the error messages or provide additional validation:
//! A [custom parser][TypedValueParser] can be used to improve the error messages or provide additional validation:
//!
//! ```rust
#![doc = include_str!("../../examples/tutorial_derive/04_02_validate.rs")]
Expand Down Expand Up @@ -227,3 +232,19 @@
//! ```rust,no_run
#![doc = include_str!("../../examples/tutorial_derive/05_01_assert.rs")]
//! ```
//!
//! ## Next Steps
//!
//! - [Cookbook][crate::_cookbook] for application-focused examples
//! - Explore more features in the [Derive reference][super]
//! - See also [`Command`], [`Arg`], [`ArgGroup`], and [`PossibleValue`] builder functions which
//! can be used as attributes
//!
//! For support, see [Discussions](https://github.com/clap-rs/clap/discussions)

#![allow(unused_imports)]
use crate::builder::Arg;
use crate::builder::ArgGroup;
use crate::builder::Command;
use crate::builder::PossibleValue;
use crate::builder::TypedValueParser;
30 changes: 25 additions & 5 deletions src/_tutorial.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
//! 3. [Argument Relations](#argument-relations)
//! 4. [Custom Validation](#custom-validation)
//! 5. [Testing](#testing)
//! 6. [Next Steps](#next-steps)
//!
//! See also
//! - [FAQ: When should I use the builder vs derive APIs?][crate::_faq#when-should-i-use-the-builder-vs-derive-apis]
Expand All @@ -32,6 +33,11 @@
//!
//! You can create an application with several arguments using usage strings.
//!
//! First, ensure `clap` is available:
//! ```console
//! $ cargo add clap
//! ```
//!
//! ```rust
#![doc = include_str!("../examples/tutorial_builder/01_quick.rs")]
//! ```
Expand All @@ -57,7 +63,7 @@
#![doc = include_str!("../examples/tutorial_builder/02_crate.md")]
//!
//! You can use [`Command`][crate::Command] methods to change the application level behavior of
//! clap.
//! clap, like [`Command::next_line_help`].
//!
//! ```rust
#![doc = include_str!("../examples/tutorial_builder/02_app_settings.rs")]
Expand All @@ -76,7 +82,7 @@
#![doc = include_str!("../examples/tutorial_builder/03_03_positional.md")]
//!
//! Note that the default [`ArgAction`][crate::ArgAction] is [`Set`][crate::ArgAction::Set]. To
//! accept multiple values, use [`Append`][crate::ArgAction::Append]:
//! accept multiple values, override the [action][Arg::action] with [`Append`][crate::ArgAction::Append]:
//! ```rust
#![doc = include_str!("../examples/tutorial_builder/03_03_positional_mult.rs")]
//! ```
Expand All @@ -95,7 +101,7 @@
#![doc = include_str!("../examples/tutorial_builder/03_02_option.md")]
//!
//! Note that the default [`ArgAction`][crate::ArgAction] is [`Set`][crate::ArgAction::Set]. To
//! accept multiple occurrences, use [`Append`][crate::ArgAction::Append]:
//! accept multiple occurrences, override the [action][Arg::action] with [`Append`][crate::ArgAction::Append]:
//! ```rust
#![doc = include_str!("../examples/tutorial_builder/03_02_option_mult.rs")]
//! ```
Expand Down Expand Up @@ -169,14 +175,14 @@
//!
//! ### Validated values
//!
//! More generally, you can validate and parse into any data type.
//! More generally, you can validate and parse into any data type with [`Arg::value_parser`].
//!
//! ```rust
#![doc = include_str!("../examples/tutorial_builder/04_02_parse.rs")]
//! ```
#![doc = include_str!("../examples/tutorial_builder/04_02_parse.md")]
//!
//! A custom parser can be used to improve the error messages or provide additional validation:
//! A [custom parser][TypedValueParser] can be used to improve the error messages or provide additional validation:
//!
//! ```rust
#![doc = include_str!("../examples/tutorial_builder/04_02_validate.rs")]
Expand Down Expand Up @@ -220,3 +226,17 @@
//! ```rust,no_run
#![doc = include_str!("../examples/tutorial_builder/05_01_assert.rs")]
//! ```
//!
//! ## Next Steps
//!
//! - [Cookbook][crate::_cookbook] for application-focused examples
//! - Explore more features in the [API reference][super]
//!
//! For support, see [Discussions](https://github.com/clap-rs/clap/discussions)

#![allow(unused_imports)]
use crate::builder::Arg;
use crate::builder::ArgGroup;
use crate::builder::Command;
use crate::builder::PossibleValue;
use crate::builder::TypedValueParser;