Add `cargo doc` flag or functionality to open docs at a specific crate

[nickgerace]

Problem

I believe it may be useful to add a flag or functionality to choose what crate cargo doc --open opens to. For repositories with a lot of local crates, this could be useful for newcomers who want to know where to start.

A current workaround is to generate docs for all crates and then package the specific crate you want.

cargo doc --all
cargo doc -p <desired-crate> --open

However, that workaround requires circumstantial knowledge of cargo doc. Perhaps, the spirit of what this is trying to accomplish can be achieved in one cargo doc command.

Proposed Solution

I haven't dug too deep into the cargo doc codebase yet, but generally, the solution could look like the following:

cargo doc --open-at-crate <desired-crate>

Alternatively or additionally, users could specify a "default docs crate" that cargo doc --open opens to.

[package]
default_doc_crate = "<desired-crate>"

Notes

This functionality might already exist and I could be missing something! Thanks for reading and for all contributors to cargo.

Similar issue: #3805

For opening to a specific mod, see #10516

[weihanglo]

Sorry, I didn't fully understand the problem. Doesn't cargo doc -p <package> --open fit what you need? I feel like cargo doesn't need a "build all docs" to open only the doc of a specific package with that command. Is there any prominent error preventing you from building only the specific doc?

[nickgerace]

In a repository with multiple crates using Cargo workspaces, I believe you need to build docs for all crates in the workspace and then run cargo doc -p <package> --open. I could be wrong on that, but from what I understand, the workaround I described will cover for that scenario.

cargo doc --all
cargo doc -p <desired-crate> --open

Essentially, the behavior I am identifying is the following: build docs for all crates in the Cargo workspace, and then ensure one of the crates is the "default" one that is opened. For the repository I am referencing, we have many sub-crates, so it would be a nice-to-have for there to be a "default" crate that cargo doc --open (or equivalent) lands on.

(I try to avoid off topic comments, but good to see you @weihanglo. Hope SUSE is going well 😄)

[weihanglo]

Hmm… just did a quick test with a workspace. I can open the doc of a specific crate without building all at once.

Click to see the repro script

#! /usr/bin/env bash
mkdir test-open && cd test-open

cargo new --lib a
cat <<EOF > a/src/lib.rs
/// # a
pub fn a() {}
EOF

cargo new --lib b
cat <<EOF > b/src/lib.rs
/// # b
pub fn b() {}
EOF

cargo new --lib c
cat <<EOF > c/src/lib.rs
/// # c
pub fn c() {}
EOF

cat <<EOF > Cargo.toml
[workspace]
members = ["a", "b", "c"]
EOF

And I got the point of default-doc-open. It's similar to what default-run does. I can see the value for newcomers of a project. Though I foresee people might want to --open a lot of different stuff 😆 Will bring up this to the next triage meeting if no other high priority issues.

(Off topic: Thanks! I am doing well. The only change is your leaving 🥲)