Allow skipping of specific dependencies 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 #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:

cargo-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?

[thkien]

I'm trying to find a solution for similar issue then came across this old ticket.

According to "The Cargo Book", cargo doc has following options:

• --no-deps: Do not build documentation for dependencies ... ← this is the one that solved my issue
• -p/--package spec...: Document only the specified packages ...
• --exclude SPEC...: Exclude the specified packages ...

So probably this issue should be fixed (?)

[melMass]

So probably this issue should be fixed (?)

Indeed, and the highlighted answer has nothing to do with the issue 😅

[Sunshine40]

According to "The Cargo Book", cargo doc has following options:

• --no-deps: Do not build documentation for dependencies ... ← this is the one that solved my issue

There is one problem: if package-b depends on package-a in the same workspace, then with --workspace --no-deps, everything seems fine except that the links to items in package-a are no longer available in package-b's doc pages.

Ideally, we need specific packages to be hidden from documentation, but without making package docs generated with a single command isolated from each other which is how --no-deps currently works in order not to bring up dependencies.

[ChrisDenton]

I'll note here that the link above shows this is relevant to the windows and windows-sys crates too (successors to the winapi crate). These are monolithic crates so will necessarily generate a lot of docs.

[epage]

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?

cargo doc got a --keep-going flag in #12568. Might not solve all problems but might help with some.

[epage]

Also, would #2025 reduce the impact of this?

[ChrisDenton]

cc @LikeLakers2

[LikeLakers2]

[@epage] Also, would #2025 reduce the impact of this?

In regards to the issue that I described at microsoft/windows-rs#2665 (and which was mentioned above by @ChrisDenton)? Yes, I believe it would. I don't use windows-sys or winapi directly, and most of the time it is abstracted away (i.e. by tempfile or winit), so the monolithic amount of documentation they generate is more a waste of my disk space than anything - not to mention they make cargo clean take forever.