Stream: rustdoc

Topic: Generating docs without source code


view this post on Zulip Charles Lew (Feb 19 2021 at 09:07):

Hello, i was talking today with other people about shipping pre-built rlibs. One thing that come to us is that docs is needed so people can read and understand how to use the library. However rustdoc seems to include the original source code as webpages. I wonder if there's already an option to turn that off. Thanks!

view this post on Zulip Daniel Henry-Mantilla (Feb 19 2021 at 11:47):

https://doc.rust-lang.org/rustdoc/the-doc-attribute.html#html_no_source

view this post on Zulip Joshua Nelson (Feb 19 2021 at 16:01):

is there a way we could document this better? I see this question a lot

view this post on Zulip Daniel Henry-Mantilla (Feb 19 2021 at 17:22):

I personally found that by doing:

cd src/librustdoc
rg 'src'
bat html/sources.rs
rg -C3 'include_sources'

Which lead me to html_no_source and from there I got to https://doc.rust-lang.org/rustdoc; only then did it occur to me that I could have started by looking there directly :face_palm:

view this post on Zulip Daniel Henry-Mantilla (Feb 19 2021 at 17:26):

Joshua Nelson said:

is there a way we could document this better? I see this question a lot

I'd say that some command line flag within the rustdoc CLI utility may be where people will be looking for this kind of thing first.
Maybe having a FAQ version of https://doc.rust-lang.org/rustdoc/ or just rephrasing it so that it's better referenced within search indices can suffice :shrug:

view this post on Zulip Joshua Nelson (Feb 19 2021 at 17:32):

We should probably just merge https://github.com/rust-lang/rust/pull/75522 then

view this post on Zulip Daniel Henry-Mantilla (Feb 19 2021 at 17:54):

There is always RUSTDOCFLAGS='-Zcrate-attr=doc(html_no_source)' cargo +nightly doc :smiling_devil:

view this post on Zulip Joshua Nelson (Feb 19 2021 at 17:55):

I didn't know that was a thing!

view this post on Zulip Daniel Henry-Mantilla (Feb 19 2021 at 17:56):

I've sometimes used -Zcrate-attr=feature(backtrace) so as to be able to use ::std::backtrace in the middle of random code when debugging :upside_down:

view this post on Zulip GuillaumeGomez (Feb 19 2021 at 18:51):

If we want to merge https://github.com/rust-lang/rust/pull/75522, please tell me so I update it

view this post on Zulip Noah Lev (Feb 19 2021 at 21:28):

In general, I think the Rustdoc Book is not well-known enough. I didn't realize it existed until after I started contributing to rustdoc :laughing:

view this post on Zulip GuillaumeGomez (Feb 19 2021 at 21:43):

That's a common issue for most tools actually. I really don't know how we could improve that situation... Showing that in the rustdoc error/warning messages at the end maybe?

view this post on Zulip Noah Lev (Feb 19 2021 at 21:44):

No, that seems like it would be annoying.

view this post on Zulip Noah Lev (Feb 19 2021 at 21:45):

But yeah, I doubt many people read much of the Cargo and rustc books.


Last updated: Oct 11 2021 at 22:34 UTC