Repository navigation
Add an option to exclude source code from docs #75497
Description
Activity
At least some guidance on how-to-implement-that would be really appreciated!
This is more of an issue for rustdoc, so moved to rust-lang/rust where its issue tracker resides.
The
#![doc(html_no_source)]crate level attribute prevents the source files from being emitted. Does that solve this issue?Reacted by Roman and Daniel BarkerWell, let's add one then...
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).
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).Reacted by Denis and Jonas SchievinkCurrently 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.
Reacted by DenisThis 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.
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 :)
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?
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.
I'm surprised that the source code files make such a big difference. Shouldn't it represent a very small portion of the total?
In our case it represents just under 20% of the whole docs directory.
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. ;)
Reacted by tesuji
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 docputs the source code into target/doc/src/ which is not an option. I know I canrm 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-sourceNotes