Closed
Description
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
Metadata
Metadata
Assignees
Labels
Type
Projects
Milestone
Relationships
Participants
Activity
mexus commentedon Aug 13, 2020
At least some guidance on how-to-implement-that would be really appreciated!
ehuss commentedon Aug 13, 2020
This is more of an issue for rustdoc, so moved to rust-lang/rust where its issue tracker resides.
ollie27 commentedon Aug 13, 2020
The
#![doc(html_no_source)]crate level attribute prevents the source files from being emitted. Does that solve this issue?mexus commentedon Aug 13, 2020
OMG it does! Thanks a lot, @ollie27! Although why don't we make a rustdoc flag for that?
GuillaumeGomez commentedon Aug 14, 2020
Well, let's add one then...
jonas-schievink commentedon Aug 14, 2020
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 commentedon Aug 14, 2020
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 --helpdoes not list attributes, but does list command-line flags).pickfire commentedon Aug 14, 2020
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 commentedon Aug 14, 2020
@jonas-schievink ,
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 commentedon Jul 2, 2021
#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 commentedon Jul 18, 2023
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 commentedon Jul 18, 2023
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 commentedon Jul 18, 2023
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 commentedon Jul 18, 2023
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 commentedon Jul 18, 2023
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 commentedon Jul 18, 2023
In our case it represents just under 20% of the whole docs directory.
GuillaumeGomez commentedon Jul 18, 2023
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. ;)