Adding the cargo doc --examples subcommand

[heisen-li]

Adding the cargo doc --examples subcommand

#4508

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @ehuss (or someone else) soon.

Please see the contribution instructions for more information.

[jyn514]

This doesn't actually do anything; if someone passes the option cargo will ignore it. Consider writing some tests so you can tell whether this works or not, there are lots of examples if you search for cargo_test.

I'm not super familiar with cargo's code, but I expect the right approach would be to loop over all examples and document them (maybe in parallel?). I'd look at how --example x works currently.

[heisen-li]

Thank you for your review, which is a huge encouragement to me. It works fine for my local test.

My test file directory is:

hello
├─examples
│    ├───examples1.rs
│    └───examples2.rs
└─src
   └───main.rs

I think it's good extensibility in the source code.

..\cargo\src\cargo\util\command_prelude.rs

filter: CompileFilter::from_raw_arguments(
                self._is_present("lib"),
                self._values_of("bin"),
                self._is_present("bins"),
                self._values_of("test"),
                self._is_present("tests"),
                self._values_of("example"),
                self._is_present("examples"),     // examples
                self._values_of("bench"),
                self._is_present("benches"),
                self._is_present("all-targets"),
            ),

[ehuss]

Thanks for the PR!

Just a few questions/comments:

• Can you say more about the use case here? Do you have a public project that demonstrates where this would be useful? It seems a bit unusual since you can't use example libraries as a dependency.
• I would probably just update arg_targets_lib_bin to add examples instead of adding a separate argument here, since cargo doc is the only command that uses arg_targets_lib_bin.
• This should probably support both --examples and --example.
• All additions need tests to be added. There's more information at https://doc.crates.io/contrib/tests/index.html about writing and running tests.
• CLI changes need to be added to the man pages. There is some documentation here that explains how that works.

[heisen-li]

Frankly, I don't have any more use cases here.I think it is a legacy issue.Maybe you're busy, so I'll help you out.

In addition, the test items I conducted locally were normal, but I failed here. Why?

[jyn514]

Can you say more about the use case here? Do you have a public project that demonstrates where this would be useful? It seems a bit unusual since you can't use example libraries as a dependency.

For consistency with the other cargo subcommands. It seems weird you can use cargo check --examples and cargo doc --example x but not cargo doc --examples.

(That said, I agree I'm not sure how useful documenting examples is, I think rust-lang/rfcs#3123 is more useful.)

[ehuss]

In addition, the test items I conducted locally were normal, but I failed here. Why?

When changing the man pages, the build-man.sh script needs to be run to rebuild them, and then you need to check in all those changes.

[heisen-li]

In addition, the test items I conducted locally were normal, but I failed here. Why?

When changing the man pages, the build-man.sh script needs to be run to rebuild them, and then you need to check in all those changes.

thanks for your advice. It's normal now.

[ehuss]

Thanks!

@bors r+

[bors]

📌 Commit 92c35f2 has been approved by ehuss

[bors]

⌛ Testing commit 92c35f2 with merge 54c341d...

[bors]

☀️ Test successful - checks-actions
Approved by: ehuss
Pushing 54c341d to master...