Cargo rustdoc --deps flag (inverse of cargo doc --no-deps)?

tools and infrastructure cargo
1

Hello,

I have been working on docs.rs-like functionality for Shipyard.rs, and as part of that I have been learning about the subtle differences between cargo doc and cargo rustdoc (specifically, in allowing/handling command line flags differently).

One hurdle I've run into is in trying to get cargo rustdoc to generate docs for deps, similar to how cargo doc works. cargo doc has a --no-deps flag (it builds deps by default), but cargo rustdoc (which does not build deps by default) does not have a corresponding --deps flag to enable building deps.

The deps vs. no deps handling is quite simple at first glance. in src/bin/cargo/commands/doc.rs, the value is set based on whether the --no-deps flag is present:

    let mode = CompileMode::Doc {
        deps: !args.flag("no-deps"),
    };

...vs in src/bin/cargo/commands/rustdoc.rs, deps is hard-coded to false (i.e. mode is set to CompileMode::Doc { deps: false }).

This may seem trivial since the two commands do the same thing, but the differences between how the two commands handle flags are significant, and much existing code in docs.rs et al. I'm diving into is written targeting the rustdoc command (not doc).

So I began to wonder if it would be a good idea to add a --deps flag to cargo rustdoc. I did a quick check and simply hard-coding the opposite value in src/bin/cargo/commands/rustdoc.rs for deps (i.e. declaring mode as CompileMode::Doc { deps: true }) does exactly what I want. Thus if cargo rustdoc had a --deps flag (or checked for an env var, or had some way to control this) it would solve my problem. Rather than filing a PR I thought I would solicit feedback here first.

I am open to redirection on this:

  • is there a reason I don't understand that building docs for only the target/top-level crate is better? Personally I like the list of crates in the sidebar and I have sometimes experienced differences in output between local cargo doc and the docs.rs output (but can't find any now).

  • am I missing some simple way to get rustdoc to build docs for deps? Without any idea it seems like it would involve a bit of work, in terms of identifying how to extract the set of deps that need to be built (and this already exists, so seems like it'd be a waste of time).

Thanks for any feedback you can provide. As an aside, I am enjoying groking the code of tools I have been using for years (rustwide is pretty cool!), and appreciate all the hard work that has gone into making rust build tooling a A+ experience.

2

cargo rustdoc does not build the dependencies because it is intended to only run for a single crate. It is intended as a low-level command, somewhat equivalent to running rustdoc directly, but with a few extra flags wired up so that it can run with a Cargo project.

If you want to pass flags to all rustdoc invocations, I suggest using cargo doc with RUSTDOCFLAGS. If you want to build all dependencies with one set of flags, and the top-level package with a different set of flags, you can try something like:

  1. RUSTDOCFLAGS="dependency flags" cargo doc
  2. cargo rustdoc -- top-level-flags-here

That will unfortunately build the top-level twice. It would be possible to avoid that by instead using a RUSTDOC wrapper which inspects the crate name to decide which flags to pass.

If that isn't what you are looking for, perhaps you can explain more what you are trying to accomplish?

3

This topic was automatically closed 540 days after the last reply. New replies are no longer allowed.