Cargo: Allow skipping of specific crates in 'cargo doc'

[LPGhatguy]

When building projects on Windows that use winapi somewhere in a downstream dependency, generating documentation takes a long time. Usually in these projects, I don't actually care about winapi types; the extra 20 minutes before I can use the documentation I _do_ care about is a drag!

Does it make sense to be able to skip documentation of a specific crate, like cargo doc --skip-package winapi? Any references to the types re-exported by crates I consume directly would have issues, I assume.

[alexcrichton]

Perhaps https://github.com/rust-lang/cargo/pull/4031 would help here?

[carols10cents]

I don't think --exclude helps here, since --exclude only works with --all and --all only works with workspaces.

From a non-workspace crate that lists rand as a dependency:

$ cargo doc --exclude rand
error: Unknown flag: '--exclude'

Usage:
    cargo doc [options]

$ cargo doc --all --exclude rand
error: Unknown flag: '--exclude'

Usage:
    cargo doc [options]

[icefoxen]

I second this; this is troublesome for gfx-rs, which has many sub-crates which only work on certain platforms. Trying to even run cargo doc on it will always try to build at least one thing which can't build on any platform.

[searing]

This would be great - trying to document even simple crates can easily take a very long time.

I think the ideal solution would be a way to (optionally) externally link to docs.rs for crates.io dependencies. But, barring that, simply not linking anywhere would be a nice feature. I really don't need to generate a local copy of Diesel's documentation for a simple one-file library that uses it, for example.

[jesskfullwood]

Worth noting that crates sometime fail to compile the docs while otherwise working fine. This is currently the case with diesel on nightly. I'm unable to generate docs for my own project at the moment due to the diesel dependency

[brokenthorn]

What about a --project-only flag? (maybe use docs.rs for external links)

[brokenthorn]

What about a --project-only flag? (maybe use docs.rs for external links)

Sorry. Looks like I only had to check cargo help doc:

Build a package's documentation

USAGE:
    cargo doc [OPTIONS]

OPTIONS:
        --open                      Opens the docs in a browser after the operation
    -p, --package <SPEC>...         Package to document
        --all                       Document all packages in the workspace
        --exclude <SPEC>...         Exclude packages from the build
        --no-deps                   Don't build documentation for dependencies
        --document-private-items    Document private items
    -j, --jobs <N>                  Number of parallel jobs, defaults to # of CPUs
        --lib                       Document only this package's library
        --bin <NAME>...             Document only the specified binary
        --bins                      Document all binaries
        --release                   Build artifacts in release mode, with optimizations
        --features <FEATURES>       Space-separated list of features to activate
        --all-features              Activate all available features
        --no-default-features       Do not activate the `default` feature
        --target <TRIPLE>           Build for the target triple
        --target-dir <DIRECTORY>    Directory for all generated artifacts
        --manifest-path <PATH>      Path to Cargo.toml
        --message-format <FMT>      Error format [default: human]  [possible values: human, json, short]
    -v, --verbose                   Use verbose output (-vv very verbose/build.rs output)
    -q, --quiet                     No output printed to stdout
        --color <WHEN>              Coloring: auto, always, never
        --frozen                    Require Cargo.lock and cache are up to date
        --locked                    Require Cargo.lock is up to date
    -Z <FLAG>...                    Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
    -h, --help                      Prints help information

By default the documentation for the local package and all dependencies is
built. The output is all placed in `target/doc` in rustdoc's usual format.

All packages in the workspace are documented if the `--all` flag is supplied. The
`--all` flag is automatically assumed for a virtual manifest.
Note that `--exclude` has to be specified in conjunction with the `--all` flag.

If the --package argument is given, then SPEC is a package id specification
which indicates which package should be documented. If it is not given, then the
current package is documented. For more information on SPEC and its format, see
the `cargo help pkgid` command.

[cpick]

The original request was motivated by wanting to decrease doc-build times, but some of the additional use cases (including my own) are due to wanting documentation for other dependencies even if one fails to build.

This case would certainly be well served by an ability to manually skip the problematic crate(s), but also by a --persist-through-errors option if that could be made to continue generating the rest of the documentation.

If that sounds possible (or easier than --skip-crate) I could open a new issues to request that option?