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

```bash #! /usr/bin/env bash mkdir test-open && cd test-open cargo new --lib a cat < a/src/lib.rs /// # a pub fn a() {} EOF cargo new --lib b cat < b/src/lib.rs /// # b pub fn b() {} EOF cargo new --lib c cat < c/src/lib.rs /// # c pub fn c() {} EOF cat < 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 🥲)