Cargo doc: is it possible to document only one dependency

help
1

Right now my CI is running cargo doc --no-default-features --features="docs" --no-deps --workspace but I want one and only one child crate also to be included in the documentation. Is this possible at all (nightly or not)?

I want to include the vrl crate in the docs. I'm not opposed to running multiple commands or to any hackery I may have to do, I just want it to work.

Makefile

What I tried:

cargo doc --no-default-features --features="docs" --no-deps --workspace -p vrl

and got

error: package(s) `vrl` not found in workspace

While looking this up I also found GitHub - Bunogi/cargo-makedocs: A cargo subcommand to build documentation for development easier but reading the source code it looks like it only would've done the same command I tried before... Any help is appreciated.

2

vrl is an upstream dependency of your workspace, correct? Have you tried cargo doc -p vrl --no-deps?

3

Multiple commands are the way. Simply run cargo doc -p vrl --no-deps. Documentation always indexes all crates that have been documented since the last cargo clean — there is no need to specify all wanted packages in the same command.

4

Hi all, thanks for the replies. Yes, vrl is an upstream dependency of my workspace and not a local lib.

It seems like adding a separate cargo doc -p vrl --no-deps command made the vrl crate documentation available. This fixed my issue, so thanks a lot!

What was tripping me up is that running cargo doc -p vrl --workspace errors out because it tries to find the local lib inside the workspace. AKA --workspace completely changes the behavior of -p. IMO this should be better documented (maybe even a bug?). Either way, thanks!

5

What did you expect --workspace to do, if not change behavior of -p?

(I'm not criticising, only trying to figure out what needs to be clarified in the error messages or docs)

6

Myself, not re-reading the docs, I know --workspace as one of the “package selection options” (and --package is one of those too), which changes the package selection from the default set (workspace.default-members) to all of workspace.members.

Before reading this thread, I would have expected --workspace --package=foo to mean one or the other of

  • “all of the packages in the workspace AND foo”, like specifying --package more than once
  • “error: specify only one of --workspace or --package, not both”

It’s surprising to me that --workspace is in any way a modifier to --package's behavior, rather than being either independent or conflicting, and I don’t see what scenario that behavior would be useful in.

3 Likes
7

Yep, you pretty much summed what I was going to reply @kpreid.

I'd expect it to work like check/build does.

  1. cargo doc: documents the main crate (with deps)
  2. cargo doc --no-deps: documents the main crate (without deps)
  3. cargo doc --workspace documents the main crate and workspace crates

I now know that this is wrong (#1 and #3) but that's what I thought --workspace meant and therefore, by that logic, cargo doc --no-deps -p crate and cargo doc --workspace --no-deps -p crate behaving differently is unintuitive.

1 Like