Add an option to exclude source code from docs

[kpp]

Describe the problem you are trying to solve

I ship a proprietary cdylib which I build from Rust code. I want to document the API using doc comments. However at the moment cargo doc puts the source code into target/doc/src/ which is not an option. I know I can rm target/doc/src/ however there is [src](goto source code) button left in the top right corner of the docs.

Describe the solution you'd like

cargo doc --exclude-source

Notes

[mexus]

At least some guidance on how-to-implement-that would be really appreciated!

[ehuss]

This is more of an issue for rustdoc, so moved to rust-lang/rust where its issue tracker resides.

[ollie27]

The #![doc(html_no_source)] crate level attribute prevents the source files from being emitted. Does that solve this issue?

[mexus]

OMG it does! Thanks a lot, @ollie27! Although why don't we make a rustdoc flag for that?

[GuillaumeGomez]

Well, let's add one then...

[jonas-schievink]

Does it make sense to have both an attribute and a command line flag for this? This doesn't seem like something you'd want to configure on a per-invocation basis, it's more like something that's permanent for a given code base (so the attributes fits better).

[Lonami]

I think it fits the use case of being able to produce end-user documentation (without source links if providing binaries only) and internal documentation (with source links that may be helpful in some cases). I'm guessing it would also be more discoverable (rustdoc --help does not list attributes, but does list command-line flags).

[pickfire]

Currently the only way to find this is through rustdoc book, which may not be quite discoverable if the users didn't saw that. I wish there is a manpage for rustdoc book but still currently man pages for rust is still not very good yet since we haven't figured out how to get to show the correct man pages for the current directory.

[mexus]

@jonas-schievink ,

This doesn't seem like something you'd want to configure on a per-invocation basis, it's more like something that's permanent for a given code base (so the attributes fits better).

Well, while the attribute is kinda sufficient, it would be also great to have an option to jump-to-source-code during the development phase. On the other hand, the attribute could be disabled/enabled with a feature flag, so having a rustdoc flag is not exactly required.