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.

[jyn514]

#75522 was closed as won't fix since there are already ways to do this and it's not standard to duplicate attributes as arguments.

[kyrias]

Is there currently any way to disable source generation for the current crate and all dependencies on stable? The suggestion from that PR requires an unstable flag that doesn't appear to have had any stabilization plans since it was added in #52355.

[jyn514]

no. i would like to stabilize that flag but i don't think it currently has a tracking issue. i am happy to mentor that work if you're interested in contributing :)

[GuillaumeGomez]

I think it deserves some more discussion: on docs.rs, users will still be able to browse the source code with docs.rs code viewer. But also, when building such crates locally, nothing prevent users to actually read the code they downloaded. So maybe a broader point of view should be taken here?

[kyrias]

Personally the reason we had a need for this is because the docs for our project ended up getting big enough to reach a file size limit in our internal docs deployment, and so we wanted to be able to disable the source generation since we simply have no use for it and it ends up taking up a significant chunk of the output size.

For now we're disabling building docs for dependencies instead, but it's rather unfortunate because having the docs for dependencies built with the correct features is very useful.

[GuillaumeGomez]

I'm surprised that the source code files make such a big difference. Shouldn't it represent a very small portion of the total?

[kyrias]

In our case it represents just under 20% of the whole docs directory.

[GuillaumeGomez]

Wow, that's a lot. With this in mind, the option makes a lot more sense. Thanks for explaining. So for next steps, just as jyn514 explained. ;)