Auto merge of #10578 - epage:add-docs, r=ehuss

Document cargo-add

### What does this PR try to resolve?

cargo-add's PR was minimal to ensure we had settled on the CLI before
adding references to the CLI and have cascading churn.  This the command
documentation and adds references to that command.

### How should we test and review this PR?

I'm unsure what testing is not automated for the documentation (like link checking).

### Additional information

To keep the PRs focused, I am submitting completions separate from documentation updates so one does not get blocked on the other and its easier to see all relevant parts and sign off on them.

src/bin/cargo/cli.rs

@@ -438,6 +438,7 @@ Some common cargo commands are (see all commands with --list):
     doc, d      Build this package's and its dependencies' documentation
     new         Create a new cargo package
     init        Create a new cargo package in an existing directory
+    add         Add dependencies to a manifest file
     run, r      Run a binary or example of the local package
     test, t     Run the tests
     bench       Run the benchmarks

src/doc/man/cargo-add.md

@@ -0,0 +1,157 @@
+# cargo-add(1)
+{{*set actionverb="Add"}}
+{{*set nouns="adds"}}
+
+## NAME
+
+cargo-add - Add dependencies to a Cargo.toml manifest file
+
+## SYNOPSIS
+
+`cargo add` [_options_] _crate_...\
+`cargo add` [_options_] `--path` _path_\
+`cargo add` [_options_] `--git` _url_ [_crate_...]\
+
+
+## DESCRIPTION
+
+This command can add or modify dependencies.
+
+The source for the dependency can be specified with:
+
+* _crate_`@`_version_: Fetch from a registry with a version constraint of "_version_"
+* `--path` _path_: Fetch from the specified _path_
+* `--git` _url_: Pull from a git repo at _url_
+
+If no source is specified, then a best effort will be made to select one, including:
+
+* Existing dependencies in other tables (like `dev-dependencies`)
+* Workspace members
+* Latest release in the registry
+
+When you add a package that is already present, the existing entry will be updated with the flags specified.
+
+## OPTIONS
+
+### Source options
+
+{{#options}}
+
+{{#option "`--git` _url_" }}
+[Git URL to add the specified crate from](../reference/specifying-dependencies.html#specifying-dependencies-from-git-repositories).
+{{/option}}
+
+{{#option "`--branch` _branch_" }}
+Branch to use when adding from git.
+{{/option}}
+
+{{#option "`--tag` _tag_" }}
+Tag to use when adding from git.
+{{/option}}
+
+{{#option "`--rev` _sha_" }}
+Specific commit to use when adding from git.
+{{/option}}
+
+{{#option "`--path` _path_" }}
+[Filesystem path](../reference/specifying-dependencies.html#specifying-path-dependencies) to local crate to add.
+{{/option}}
+
+{{> options-registry }}
+
+{{/options}}
+
+### Section options
+
+{{#options}}
+
+{{#option "`--dev`" }}
+Add as a [development dependency](../reference/specifying-dependencies.html#development-dependencies).
+{{/option}}
+
+{{#option "`--build`" }}
+Add as a [build dependency](../reference/specifying-dependencies.html#build-dependencies).
+{{/option}}
+
+{{#option "`--target` _target_" }}
+Add as a dependency to the [given target platform](../reference/specifying-dependencies.html#platform-specific-dependencies).
+{{/option}}
+
+{{/options}}
+
+
+</dl>
+
+### Dependency options
+
+{{#options}}
+
+{{#option "`--rename` _name_" }}
+[Rename](../reference/specifying-dependencies.html#renaming-dependencies-in-cargotoml) the dependency.
+{{/option}}
+
+{{#option "`--optional`" }}
+Mark the dependency as [optional](../reference/features.html#optional-dependencies).
+{{/option}}
+
+{{#option "`--no-optional`" }}
+Mark the dependency as [required](../reference/features.html#optional-dependencies).
+{{/option}}
+
+{{#option "`--no-default-features`" }}
+Disable the [default features](../reference/features.html#dependency-features).
+{{/option}}
+
+{{#option "`--default-features`" }}
+Re-enable the [default features](../reference/features.html#dependency-features).
+{{/option}}
+
+{{#option "`--features` _features_" }}
+Space or comma separated list of [features to
+activate](../reference/features.html#dependency-features). When adding multiple
+crates, the features for a specific crate may be enabled with
+`package-name/feature-name` syntax. This flag may be specified multiple times,
+which enables all specified features.
+{{/option}}
+
+{{/options}}
+
+
+### Display Options
+
+{{#options}}
+{{> options-display }}
+{{/options}}
+
+### Manifest Options
+
+{{#options}}
+{{> options-manifest-path }}
+{{/options}}
+
+{{> section-options-common }}
+
+{{> section-environment }}
+
+{{> section-exit-status }}
+
+## EXAMPLES
+
+1. Add `regex` as a dependency
+
+       cargo add regex
+
+2. Add `trybuild` as a dev-dependency
+
+       cargo add --dev trybuild
+
+3. Add an older version of `nom` as a dependency
+
+       cargo add nom@5
+
+4. Add support for serializing data structures to json with `derive`s
+
+       cargo add serde serde_json -F serde/derive
+
+## SEE ALSO
+{{man "cargo" 1}}

src/doc/man/generated_txt/cargo-add.txt

@@ -0,0 +1,180 @@
+CARGO-ADD(1)
+
+NAME
+       cargo-add - Add dependencies to a Cargo.toml manifest file
+
+SYNOPSIS
+       cargo add [options] crate...
+       cargo add [options] --path path
+       cargo add [options] --git url [crate...]
+
+DESCRIPTION
+       This command can add or modify dependencies.
+
+       The source for the dependency can be specified with:
+
+       o  crate@version: Fetch from a registry with a version constraint of
+          "version"
+
+       o  --path path: Fetch from the specified path
+
+       o  --git url: Pull from a git repo at url
+
+       If no source is specified, then a best effort will be made to select
+       one, including:
+
+       o  Existing dependencies in other tables (like dev-dependencies)
+
+       o  Workspace members
+
+       o  Latest release in the registry
+
+       When you add a package that is already present, the existing entry will
+       be updated with the flags specified.
+
+OPTIONS
+   Source options
+       --git url
+           Git URL to add the specified crate from
+           <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-dependencies-from-git-repositories>.
+
+       --branch branch
+           Branch to use when adding from git.
+
+       --tag tag
+           Tag to use when adding from git.
+
+       --rev sha
+           Specific commit to use when adding from git.
+
+       --path path
+           Filesystem path
+           <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-path-dependencies>
+           to local crate to add.
+
+       --registry registry
+           Name of the registry to use. Registry names are defined in Cargo
+           config files
+           <https://doc.rust-lang.org/cargo/reference/config.html>. If not
+           specified, the default registry is used, which is defined by the
+           registry.default config key which defaults to crates-io.
+
+   Section options
+       --dev
+           Add as a development dependency
+           <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#development-dependencies>.
+
+       --build
+           Add as a build dependency
+           <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#build-dependencies>.
+
+       --target target
+           Add as a dependency to the given target platform
+           <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#platform-specific-dependencies>.
+
+</dl>
+
+   Dependency options
+       --rename name
+           Rename
+           <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#renaming-dependencies-in-cargotoml>
+           the dependency.
+
+       --optional
+           Mark the dependency as optional
+           <https://doc.rust-lang.org/cargo/reference/features.html#optional-dependencies>.
+
+       --no-optional
+           Mark the dependency as required
+           <https://doc.rust-lang.org/cargo/reference/features.html#optional-dependencies>.
+
+       --no-default-features
+           Disable the default features
+           <https://doc.rust-lang.org/cargo/reference/features.html#dependency-features>.
+
+       --default-features
+           Re-enable the default features
+           <https://doc.rust-lang.org/cargo/reference/features.html#dependency-features>.
+
+       --features features
+           Space or comma separated list of features to activate
+           <https://doc.rust-lang.org/cargo/reference/features.html#dependency-features>.
+           When adding multiple crates, the features for a specific crate may
+           be enabled with package-name/feature-name syntax. This flag may be
+           specified multiple times, which enables all specified features.
+
+   Display Options
+       -v, --verbose
+           Use verbose output. May be specified twice for "very verbose" output
+           which includes extra output such as dependency warnings and build
+           script output. May also be specified with the term.verbose config
+           value <https://doc.rust-lang.org/cargo/reference/config.html>.
+
+       -q, --quiet
+           Do not print cargo log messages. May also be specified with the
+           term.quiet config value
+           <https://doc.rust-lang.org/cargo/reference/config.html>.
+
+       --color when
+           Control when colored output is used. Valid values:
+
+           o  auto (default): Automatically detect if color support is
+              available on the terminal.
+
+           o  always: Always display colors.
+
+           o  never: Never display colors.
+
+           May also be specified with the term.color config value
+           <https://doc.rust-lang.org/cargo/reference/config.html>.
+
+   Manifest Options
+       --manifest-path path
+           Path to the Cargo.toml file. By default, Cargo searches for the
+           Cargo.toml file in the current directory or any parent directory.
+
+   Common Options
+       +toolchain
+           If Cargo has been installed with rustup, and the first argument to
+           cargo begins with +, it will be interpreted as a rustup toolchain
+           name (such as +stable or +nightly). See the rustup documentation
+           <https://rust-lang.github.io/rustup/overrides.html> for more
+           information about how toolchain overrides work.
+
+       -h, --help
+           Prints help information.
+
+       -Z flag
+           Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
+           details.
+
+ENVIRONMENT
+       See the reference
+       <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
+       for details on environment variables that Cargo reads.
+
+EXIT STATUS
+       o  0: Cargo succeeded.
+
+       o  101: Cargo failed to complete.
+
+EXAMPLES
+       1. Add regex as a dependency
+
+              cargo add regex
+
+       2. Add trybuild as a dev-dependency
+
+              cargo add --dev trybuild
+
+       3. Add an older version of nom as a dependency
+
+              cargo add nom@5
+
+       4. Add support for serializing data structures to json with derives
+
+              cargo add serde serde_json -F serde/derive
+
+SEE ALSO
+       cargo(1)
+

src/doc/src/SUMMARY.md

@@ -61,6 +61,7 @@
         * [cargo test](commands/cargo-test.md)
         * [cargo report](commands/cargo-report.md)
     * [Manifest Commands](commands/manifest-commands.md)
+        * [cargo add](commands/cargo-add.md)
         * [cargo generate-lockfile](commands/cargo-generate-lockfile.md)
         * [cargo locate-project](commands/cargo-locate-project.md)
         * [cargo metadata](commands/cargo-metadata.md)