Stream: rustdoc

Topic: Recruiting new rustdoc members


view this post on Zulip Joshua Nelson (Nov 24 2020 at 14:25):

After the conversation in https://rust-lang.zulipchat.com/#narrow/stream/245100-t-compiler.2Fwg-prioritization.2Falerts/topic/I-prioritize.20.2379103.20Rustdoc.20takes.208.2E5.20GB.20of.20memory.20to.20docum.E2.80.A6, @apiraino suggested that we start recruiting new people for rustdoc so I don't feel like I'm trying to do everything myself. We were thinking of writing a blog post in the spirit of https://blog.rust-lang.org/2020/09/14/wg-prio-call-for-contributors.html with vaguely this info:

  1. What rustdoc is and why it's important
  2. How you can help

It would be nice as part of 2. to also tag some issues as E-mentor.

view this post on Zulip Joshua Nelson (Nov 24 2020 at 14:25):

one thing we discussed is that both docs.rs and rustdoc could really use a changelog, right now there are a lot of changes coming in that aren't documented terribly well

view this post on Zulip Joshua Nelson (Nov 24 2020 at 14:26):

and the nice thing about that is it doesn't require any experience, you just search label:T-rustdoc is:pr is:merged

view this post on Zulip simulacrum (Nov 24 2020 at 14:27):

I would suggest against framing this specifically as a "new team members" thing, but more so that you're looking for contributors. Along side that you can publish a "pathway to membership" (e.g., frequent contributor over 2-3 months and contributes to design discussion)

view this post on Zulip Joshua Nelson (Nov 24 2020 at 14:27):

right, that's what I meant. I like the pathway to membership idea :)

view this post on Zulip Joshua Nelson (Nov 24 2020 at 14:28):

we have been getting a fair amount of new contributors lately so I think there's already interest if we can get the word out

view this post on Zulip Nelson J Morais (Nov 24 2020 at 15:04):

hello

view this post on Zulip Nelson J Morais (Nov 24 2020 at 15:06):

:wave:

view this post on Zulip Joshua Nelson (Nov 24 2020 at 15:10):

Welcome! Are you looking to work on rustdoc?

view this post on Zulip Nelson J Morais (Nov 24 2020 at 15:10):

yeap

view this post on Zulip Nelson J Morais (Nov 24 2020 at 15:10):

I've been reading about it.

view this post on Zulip Nelson J Morais (Nov 24 2020 at 15:11):

I need to start diving into the code now, to see what that clean::DocContext does.. :smile:

view this post on Zulip Nelson J Morais (Nov 24 2020 at 15:12):

but if there's any e-easy issues I'll be happy to look at them

view this post on Zulip Joshua Nelson (Nov 24 2020 at 15:13):

I think https://github.com/rust-lang/rust/issues/70898 is the only one tagged as easy that needs work, but there are probably a lot more that just haven't been tagged

view this post on Zulip Joshua Nelson (Nov 24 2020 at 15:14):

Feel free to look at any issues tagged T-rustdoc

view this post on Zulip Nelson J Morais (Nov 24 2020 at 15:14):

Ok great, I'll do that!

view this post on Zulip Joshua Nelson (Nov 24 2020 at 15:14):

Nelson J Morais said:

I need to start diving into the code now, to see what that clean::DocContext does.. :)

consider reading through https://rustc-dev-guide.rust-lang.org/rustdoc.html instead, the code is a little hard to follow IMO

view this post on Zulip Nelson J Morais (Nov 24 2020 at 15:22):

yes I've done it, but that rust doc chapter is not so much detailed like for instance the query system

view this post on Zulip Nelson J Morais (Nov 24 2020 at 15:23):

but thanks for info!

view this post on Zulip Joshua Nelson (Nov 24 2020 at 15:23):

did you see the next page too? https://rustc-dev-guide.rust-lang.org/rustdoc-internals.html

view this post on Zulip Nelson J Morais (Nov 24 2020 at 15:24):

yeah I "heard" somewhere that the rust doc code is becoming hard to maintain :smile:

view this post on Zulip Joshua Nelson (Nov 24 2020 at 15:24):

I don't know if becoming is the right word :sweat_smile:

view this post on Zulip Joshua Nelson (Nov 24 2020 at 15:24):

it's been like this a while

view this post on Zulip Nelson J Morais (Nov 24 2020 at 15:25):

to be honest, not sure about internals.. I think so (am at mobile right now, have the rust-dev-guide open on laptop) either way I'll read it.

view this post on Zulip Joshua Nelson (Nov 24 2020 at 15:25):

it has a lot more info than the overview page

view this post on Zulip Joshua Nelson (Nov 24 2020 at 15:26):

the main page is the bare minimum 'how do I build rustdoc' bascially

view this post on Zulip Nelson J Morais (Nov 24 2020 at 15:28):

will do that.

view this post on Zulip Nelson J Morais (Nov 24 2020 at 15:30):

altough, definitely will read that "how I build rustdoc" section... most of the inicial pain point will be to find a fast iteration workflow to change, build, test... with fast compilation times

view this post on Zulip GuillaumeGomez (Nov 24 2020 at 15:36):

oh boy XD

view this post on Zulip GuillaumeGomez (Nov 24 2020 at 15:38):

But in any case, if you lack information on something, please ask us so that we can help you and also improve the internal rustdoc book to help other newcomers.

view this post on Zulip Nelson J Morais (Nov 24 2020 at 15:57):

GuillaumeGomez said:

oh boy XD

sounds comforting :sweat_smile:

view this post on Zulip Nelson J Morais (Nov 24 2020 at 15:58):

but yeah.. I'll bug you all if I find roadblocks :smile:

view this post on Zulip Nelson J Morais (Nov 24 2020 at 18:42):

d:\Code\rust\rust\(patch_rustdoc)> x.py build library/test
Updating only changed submodules
Submodules updated in 0.20 seconds
downloading https://static.rust-lang.org/dist/2020-11-18/rust-std-beta-i686-pc-windows-gnu.tar.xz
extracting d:\Code\rust\rust\build\cache\2020-11-18\rust-std-beta-i686-pc-windows-gnu.tar.xz
downloading https://static.rust-lang.org/dist/2020-11-18/rustc-beta-i686-pc-windows-gnu.tar.xz
extracting d:\Code\rust\rust\build\cache\2020-11-18\rustc-beta-i686-pc-windows-gnu.tar.xz
downloading https://static.rust-lang.org/dist/2020-11-18/cargo-beta-i686-pc-windows-gnu.tar.xz
extracting d:\Code\rust\rust\build\cache\2020-11-18\cargo-beta-i686-pc-windows-gnu.tar.xz
downloading https://static.rust-lang.org/dist/2020-11-19/rustfmt-nightly-i686-pc-windows-gnu.tar.xz
extracting d:\Code\rust\rust\build\cache\2020-11-19\rustfmt-nightly-i686-pc-windows-gnu.tar.xz
downloading https://ci-artifacts.rust-lang.org/rustc-builds-alt/430feb24a46993e5073c1bb1b39da190d83fa2bf/rust-dev-nightly-i686-pc-windows-gnu.tar.xz
Exception calling "DownloadFile" with "2" argument(s): "The remote server returned an error: (404) Not Found."
At line:1 char:82
+ ... pe]::Tls12; (New-Object System.Net.WebClient).DownloadFile('https://c ...
+                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [], MethodInvocationException
    + FullyQualifiedErrorId : WebException


spurious failure, trying again
downloading https://ci-artifacts.rust-lang.org/rustc-builds-alt/430feb24a46993e5073c1bb1b39da190d
`

view this post on Zulip Nelson J Morais (Nov 24 2020 at 18:43):

is rust-dev-nightly..tar the file that contains llvm artifacts? I suspect we don't build llvm for windows?
(I do have: download-ci-llvm = true in my config.toml)

view this post on Zulip Joshua Nelson (Nov 24 2020 at 18:47):

You should remove that then

view this post on Zulip Nelson J Morais (Nov 24 2020 at 18:47):

painfull :frown: lol

view this post on Zulip Joshua Nelson (Nov 24 2020 at 18:47):

Hmm, I think the guide might recommend that - it should recommend if-available instead

view this post on Zulip Nelson J Morais (Nov 24 2020 at 18:47):

can i point config.toml to use already installed llvm binaries?
any documentation about that ?

view this post on Zulip Joshua Nelson (Nov 24 2020 at 18:47):

Sure

view this post on Zulip Joshua Nelson (Nov 24 2020 at 18:48):

https://rustc-dev-guide.rust-lang.org/building/suggested.html#skipping-llvm-build

view this post on Zulip Nelson J Morais (Nov 24 2020 at 18:48):

d:\Code\rust> ls "c:\Program Files\LLVM\"
───┬─────────────────────────────────────┬──────┬──────────┬──────────────
 # │ name                                │ type │ size     │ modified
───┼─────────────────────────────────────┼──────┼──────────┼──────────────
 0 │ c:\Program Files\LLVM\Uninstall.exe │ File │ 158.2 KB │ 6 months ago
 1 │ c:\Program Files\LLVM\bin           │ Dir  │  49.2 KB │ 6 months ago
 2 │ c:\Program Files\LLVM\include       │ Dir  │      0 B │ 6 months ago
 3 │ c:\Program Files\LLVM\lib           │ Dir  │   4.1 KB │ 6 months ago
 4 │ c:\Program Files\LLVM\libexec       │ Dir  │   4.1 KB │ 6 months ago
 5 │ c:\Program Files\LLVM\share         │ Dir  │   4.1 KB │ 6 months ago
───┴─────────────────────────────────────┴──────┴──────────┴──────────────

I think I'll try that first...

view this post on Zulip Nelson J Morais (Nov 24 2020 at 18:49):

thanks for the link Joshua! :+1:

view this post on Zulip GuillaumeGomez (Nov 24 2020 at 19:51):

I usually just run "./x.py test src/test/rustdoc"

view this post on Zulip Nelson J Morais (Nov 24 2020 at 19:54):

   Compiling test v0.0.0 (D:\Code\rust\rust\library\test)
    Finished release [optimized + debuginfo] target(s) in 1m 36s
Copying stage1 std from stage1 (x86_64-pc-windows-msvc -> x86_64-pc-windows-msvc / x86_64-pc-windows-msvc)
Build completed successfully in 0:41:16

:sweat_smile:

view this post on Zulip GuillaumeGomez (Nov 24 2020 at 19:55):

yep, first time is awfully slow

view this post on Zulip GuillaumeGomez (Nov 24 2020 at 19:55):

and with llvm it's even worse

view this post on Zulip Nelson J Morais (Nov 24 2020 at 20:02):

yeah...

view this post on Zulip Nelson J Morais (Nov 24 2020 at 20:24):

    // need to move these items separately because we lose them by the time the closure is called,
    // but we can't crates the Handler ahead of time because it's not Send
    let diag_opts = (options.error_format, options.edition, options.debugging_opts.clone());
    let show_coverage = options.show_coverage;
    let run_check = options.run_check;

    // First, parse the crate and extract all relevant information.
    info!("starting to run rustc");

isn't crates in "but we can't crates the Handler ahead of time because it's not Send" a typo in src/librustdoc/lib.rs:516?
(we could see it as a funny way to write creates..lol)

view this post on Zulip Joshua Nelson (Nov 24 2020 at 21:33):

haha, yeah that should be create

view this post on Zulip Joshua Nelson (Nov 24 2020 at 21:33):

@Nelson J Morais want to make that your first PR? :)

view this post on Zulip Noah Lev (Nov 24 2020 at 23:58):

Yes! Finally, a Zulip stream.

view this post on Zulip GuillaumeGomez (Nov 25 2020 at 00:33):

Damn it. It's now like rolling snow ball on a damn snowy slope T_T

view this post on Zulip GuillaumeGomez (Nov 25 2020 at 00:34):

@Joshua Nelson You tricked me efficiently there! Well done I guess XD

view this post on Zulip Nelson J Morais (Nov 25 2020 at 16:18):

Joshua Nelson said:

Nelson J Morais want to make that your first PR? :smile:

sure will do that later today, to celebrate the new contribution and the rustdoc stream here at zulip :smile:

view this post on Zulip Nelson J Morais (Nov 25 2020 at 19:22):

PR https://github.com/rust-lang/rust/pull/79420

view this post on Zulip apiraino (Nov 26 2020 at 12:43):

@Joshua Nelson @GuillaumeGomez a first _early_ draft of the recruiting blog post is available on hackmd. Shared it with Johua. Guillaume, are you also on hackmd? Otherwise I will send you the doc

view this post on Zulip GuillaumeGomez (Nov 26 2020 at 12:46):

I think I am, but please send me the link directly because I'll never find my name. ^^'

view this post on Zulip Joshua Nelson (Nov 26 2020 at 13:59):

@apiraino you said needs to be updated, but it is up to date - everyone listed on https://www.rust-lang.org/governance/teams/dev-tools#rustdoc is part of the team

view this post on Zulip Joshua Nelson (Nov 26 2020 at 14:01):

@apiraino where did you get the link to https://readrust.net/support ? you're right, that one's definitely out of date :sweat_smile:

view this post on Zulip apiraino (Nov 26 2020 at 14:02):

I think I've searched "rustdoc team" or something like that on ddg :)

view this post on Zulip Joshua Nelson (Nov 26 2020 at 14:02):

oof, the top hit for that for me is https://www.rust-lang.org/governance/teams/documentation :sweat_smile:

view this post on Zulip Joshua Nelson (Nov 26 2020 at 14:03):

@Steve Klabnik the documentation team doesn't really exist anymore, right? Should we take down that page from RLO?

view this post on Zulip Steve Klabnik (Nov 26 2020 at 14:03):

So yeah I have a PR to do that but they wanted an adjustment and I keep forgetting to finish it :frown:

view this post on Zulip Joshua Nelson (Nov 26 2020 at 14:03):

also google seems to be very confused about the difference between rust docs and rustdoc

view this post on Zulip Steve Klabnik (Nov 26 2020 at 14:04):

So yes we should. If anyone wants to fix it for me go ahead.

view this post on Zulip Joshua Nelson (Nov 26 2020 at 14:04):

is that https://github.com/rust-lang/team/pull/298 ?

view this post on Zulip Steve Klabnik (Nov 26 2020 at 14:04):

But I will try to at some point soon. It’s not hard, just... life is hard Hackett

view this post on Zulip Steve Klabnik (Nov 26 2020 at 14:04):

Lately (ugh phones and autocorrect)

view this post on Zulip Joshua Nelson (Nov 26 2020 at 14:05):

no problem at all :heart: I know this year has been crazy

view this post on Zulip Joshua Nelson (Nov 26 2020 at 14:06):

@apiraino I noticed you linked to issues with A-doctests - was that intentional? I was planning to link to T-rustdoc instead

view this post on Zulip apiraino (Nov 26 2020 at 14:07):

Joshua Nelson said:

apiraino I noticed you linked to issues with A-doctests - was that intentional? I was planning to link to T-rustdoc instead

please update the list of issues you would like to have prominent :thumbs_up: I've just picked a random filter

view this post on Zulip Joshua Nelson (Nov 26 2020 at 14:08):

We also welcome very much feedback about rustdoc, that’s another form of contribution that can help us get a drift of how people use rustdoc, what they like and how we can improve.

so, this is a bit of a sore point for me - feedback is definitely useful and welcome, but we have so much feedback in backlog I don't know if it's actually helpful to ask for more

view this post on Zulip Joshua Nelson (Nov 26 2020 at 14:10):

and by 'feedback in backlog' I mean things like

view this post on Zulip apiraino (Nov 26 2020 at 14:10):

Joshua Nelson said:

We also welcome very much feedback about rustdoc, that’s another form of contribution that can help us get a drift of how people use rustdoc, what they like and how we can improve.

so, this is a bit of a sore point for me - feedback is definitely useful and welcome, but we have so much feedback in backlog I don't know if it's actually helpful to ask for more

that's ok, please delete that if it doesn't match the reality. Like I said, I need the rustdoc team to validate this braindump :-) I just wanted to get things started

view this post on Zulip Joshua Nelson (Nov 26 2020 at 14:11):

like, there are definitely giant issues but when I look at them I feel a little overwhelmed :sweat_smile: so I'm not sure if asking for even more issues is helpful right now

view this post on Zulip apiraino (Nov 26 2020 at 14:11):

I've linked the blog post from Guillaume because in 2020 he specifically asked for feedback. I guess you have now more than enough :D

view this post on Zulip Joshua Nelson (Nov 26 2020 at 14:12):

oh lets loop in @GuillaumeGomez

view this post on Zulip Joshua Nelson (Nov 26 2020 at 14:12):

I hadn't read his post

view this post on Zulip apiraino (Nov 26 2020 at 14:19):

the TODOs I left are just side thoughts that came up while drafting the post: just questions to you team and they can be easily answered or removed

view this post on Zulip Joshua Nelson (Nov 26 2020 at 14:24):

@apiraino although I do think rustdoc's code is hard to follow, I'm not sure we want to put that front and center on the blog post :sweat_smile: I'm a little worried we're scaring people off with all the caveats about the difficulty

view this post on Zulip Joshua Nelson (Nov 26 2020 at 14:24):

maybe it makes sense to wait until after we move rustdoc out of tree to make the post?

view this post on Zulip Joshua Nelson (Nov 26 2020 at 14:25):

I don't know anyone that's on IRC. I'm curious why you say discord is confusing? (Zulip is understandable)

view this post on Zulip Joshua Nelson (Nov 26 2020 at 14:25):

and we should probably ask @GuillaumeGomez whether to suggest the discord or the zulip

view this post on Zulip apiraino (Nov 26 2020 at 14:27):

although I do think rustdoc's code is hard to follow, I'm not sure we want to put that front and center on the blog post :sweat_smile: I'm a little worried we're scaring people off with all the caveats about the difficulty

makes sense. On the other end I think it would be fair to set the expectations clear about contributing to the project, but please set the general "tone" of the blog post to your liking :-)

view this post on Zulip Joshua Nelson (Nov 26 2020 at 14:28):

well, I don't think it's any harder than working on the rest of the compiler

view this post on Zulip Joshua Nelson (Nov 26 2020 at 14:28):

the bar is just a lot higher than, say, clippy

view this post on Zulip Nelson J Morais (Nov 26 2020 at 14:29):

:eyes:

view this post on Zulip apiraino (Nov 26 2020 at 14:30):

I don't know anyone that's on IRC. I'm curious why you say discord is confusing? (Zulip is understandable)

what I meant (and probably failed to convey) is that people would want to know whether they should get in touch on Zulip or on Discord. I'm afraid that managing the team efforts on both platforms would be an organizational burden for you. As far as I know most teams or WG are on zulip or discord

view this post on Zulip GuillaumeGomez (Nov 26 2020 at 14:30):

I really don't like zulip but more and more teams seem to be switching to it... But for now, we can maybe mention both and maybe wait to have new members to get their opinion on this topic?

view this post on Zulip Joshua Nelson (Nov 26 2020 at 14:31):

I would prefer to decide on this before we invite more people

view this post on Zulip apiraino (Nov 26 2020 at 14:31):

I think you should be clear on where to onboard and manage people before. otherwise then you have to move people around

view this post on Zulip GuillaumeGomez (Nov 26 2020 at 14:31):

Joshua Nelson said:

I don't know anyone that's on IRC. I'm curious why you say discord is confusing? (Zulip is understandable)

Most of my interactions for development are on IRC XD

view this post on Zulip Joshua Nelson (Nov 26 2020 at 14:31):

otherwise it's confusing

view this post on Zulip Joshua Nelson (Nov 26 2020 at 14:31):

GuillaumeGomez said:

Joshua Nelson said:

I don't know anyone that's on IRC. I'm curious why you say discord is confusing? (Zulip is understandable)

Most of my interactions for development are on IRC XD

well, I meant specifically for rustdoc

view this post on Zulip GuillaumeGomez (Nov 26 2020 at 14:32):

The problem is that we're the only two active members. I prefer discord, you prefer zulip. On that stand, I don't want to force anything

view this post on Zulip apiraino (Nov 26 2020 at 14:33):

/me smiles at the joy of platform choice

view this post on Zulip GuillaumeGomez (Nov 26 2020 at 14:34):

Well, the big problem remains that we don't have an official "Rust teams hub", so that's not great :-/

view this post on Zulip apiraino (Nov 26 2020 at 14:35):

to be fair, the official rust lang website mentions Discord
https://www.rust-lang.org/governance/teams/dev-tools#rustdoc

view this post on Zulip GuillaumeGomez (Nov 26 2020 at 14:41):

Yep :p

view this post on Zulip apiraino (Nov 26 2020 at 14:41):

Joshua Nelson said:

maybe it makes sense to wait until after we move rustdoc out of tree to make the post?

@GuillaumeGomez :point_up:

up to you to decide depending on how mentoring newcomers would better work out. I don't know the timeline for moving rustdoc out of tree but I wouldn't want to make it a blocker for (say) 4~6 months.

view this post on Zulip Joshua Nelson (Nov 26 2020 at 14:42):

I think I'll have time to work on it over winter break if @GuillaumeGomez is ok with it

view this post on Zulip Joshua Nelson (Nov 26 2020 at 14:54):

tl;dr of https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/Building.20rustdoc.20out.20of.20tree: it's probably not happening in the near future, so we should publish the blog post first

view this post on Zulip GuillaumeGomez (Nov 26 2020 at 15:06):

However on that topic: isn't it possible to specify a rustc binary in the config.toml? So would already partially solve our issue no?

view this post on Zulip GuillaumeGomez (Nov 26 2020 at 15:07):

Like that, for newcomers who don't care about the compiler, they can just add this line and in 5 minutes they have a built rustdoc and std doc

view this post on Zulip Joshua Nelson (Nov 26 2020 at 15:15):

oh hmm, use rustup-toolchain-install-master but in-tree

view this post on Zulip Joshua Nelson (Nov 26 2020 at 15:15):

that's an interesting idea

view this post on Zulip Joshua Nelson (Nov 26 2020 at 15:15):

@Manish Goregaokar what do you think?

view this post on Zulip GuillaumeGomez (Nov 26 2020 at 15:55):

At least it would allow to have it already so we can take our time talking about moving out-of-tree. And it brings advantages: you can disable it if you need to update something in the compiler, no need to update the compiler version repeatedly. :)

view this post on Zulip Joshua Nelson (Nov 26 2020 at 16:01):

right, yeah I really like the flexibility that brings

view this post on Zulip Nelson J Morais (Nov 26 2020 at 16:08):

Nelson J Morais said:

altough, definitely will read that "how I build rustdoc" section... most of the inicial pain point will be to find a fast iteration workflow to change, build, test... with fast compilation times

that might help in my quest to find that fast iteration workflow ^

view this post on Zulip Joshua Nelson (Nov 26 2020 at 16:10):

@Nelson J Morais do you want to test it out? there are some ideas in https://github.com/rust-lang/rust/issues/66581 :)

view this post on Zulip Nelson J Morais (Nov 26 2020 at 16:15):

:+1: , but firstly I'll look into that issue https://github.com/rust-lang/rust/issues/70898 that you've posted yesterday...apparently is just documentation

view this post on Zulip Manish Goregaokar (Nov 26 2020 at 18:04):

Joshua Nelson said:

I would prefer to decide on this before we invite more people

strong agree

view this post on Zulip Manish Goregaokar (Nov 26 2020 at 18:05):

Joshua Nelson said:

Manish Goregaokar what do you think?

I think this can work and it's a prerequisite to making rustdoc work out of tree anyway. You'll need to get the tests to run though,

view this post on Zulip Poliorcetics (Nov 26 2020 at 19:02):

Hello ! I would very much like to contribute to rustdoc (and get back to contributing to std) but I’m not sure if I’ll consistently find time each week, is there something easy I can start with ?

view this post on Zulip Joshua Nelson (Nov 26 2020 at 19:03):

hmm, this is actually one of the things we need help with, going through the issues and finding which are hard and which are easy

view this post on Zulip Joshua Nelson (Nov 26 2020 at 19:04):

if you want to look at all issues, there's a list here: https://github.com/rust-lang/rust/labels/T-rustdoc

view this post on Zulip Joshua Nelson (Nov 26 2020 at 19:04):

unfortunately most of the mentored issues have already been claimed https://github.com/rust-lang/rust/issues?q=is%3Aopen+label%3AT-rustdoc+label%3AE-mentor

view this post on Zulip GuillaumeGomez (Nov 26 2020 at 19:32):

Manish Goregaokar said:

Joshua Nelson said:

Manish Goregaokar what do you think?

I think this can work and it's a prerequisite to making rustdoc work out of tree anyway. You'll need to get the tests to run though,

What's the big deal about the out of tree btw? I thought it was mostly about the compile-time but it seems that I misunderstood it completely. :-/

view this post on Zulip Joshua Nelson (Nov 26 2020 at 19:33):

I mostly wanted it for compile times

view this post on Zulip Joshua Nelson (Nov 26 2020 at 19:34):

I'm not sure why @Manish Goregaokar wanted rustdoc to be usable out-of-tree

view this post on Zulip Manish Goregaokar (Nov 26 2020 at 20:00):

because it's a real pain and a bad onboarding experience

view this post on Zulip Manish Goregaokar (Nov 26 2020 at 20:00):

people aren't used to the rustc build system

view this post on Zulip Manish Goregaokar (Nov 26 2020 at 20:01):

compile time is a part of it but people need to mess with stages, etc

view this post on Zulip Manish Goregaokar (Nov 26 2020 at 20:01):

with clippy it's just cargo test

view this post on Zulip Manish Goregaokar (Nov 26 2020 at 20:01):

and this is a huge part why clippy is easy to contribute to

view this post on Zulip Joshua Nelson (Nov 26 2020 at 20:09):

ah ok, that makes sense

view this post on Zulip Joshua Nelson (Nov 26 2020 at 20:09):

yeah having cargo test 'just work' would be really nice

view this post on Zulip GuillaumeGomez (Nov 26 2020 at 20:33):

Manish Goregaokar said:

with clippy it's just cargo test

With cargo too and yet you don't see huge contributions. I don't think this is where most of the newcomers difficulty is to be honest.

view this post on Zulip Noah Lev (Nov 26 2020 at 20:39):

Heh, I actually find rustdoc easier to contribute to.

view this post on Zulip Joshua Nelson (Nov 26 2020 at 20:40):

oh? why's that?

view this post on Zulip Noah Lev (Nov 26 2020 at 20:40):

All I do is run ./x.py build and ./x.py test src/test/rustdoc --bless and it handles everything for me

view this post on Zulip Noah Lev (Nov 26 2020 at 20:41):

With Clippy, you can run cargo build and cargo test, but you also have to run another script to bless tests

view this post on Zulip Noah Lev (Nov 26 2020 at 20:41):

But I think perhaps the biggest thing is that the subtree situation kind of confuses me

view this post on Zulip Noah Lev (Nov 26 2020 at 20:41):

It's nice to be able to have everything in one repo

view this post on Zulip Noah Lev (Nov 26 2020 at 20:42):

I find having one, dedicated script to be easier, rather than several different things

view this post on Zulip GuillaumeGomez (Nov 26 2020 at 20:42):

I appreciate that too. It makes links between components easier. But I understand that some might disagree

view this post on Zulip Noah Lev (Nov 26 2020 at 20:42):

But perhaps I'm just used to x.py and not used to Clippy's system, and that's why

view this post on Zulip GuillaumeGomez (Nov 26 2020 at 20:43):

And to be honest, with the recent merge of gtk-rs, I'm more in favor of single repositories, it made things much simpler.

view this post on Zulip Noah Lev (Nov 26 2020 at 20:45):

The joy of the monorepo :)

view this post on Zulip GuillaumeGomez (Nov 26 2020 at 20:48):

I had better experience with monorepo overall haha

view this post on Zulip Noah Lev (Nov 26 2020 at 20:49):

I didn't even realize there were plans to make a separate repo for rustdoc. Can you point me to the discussion?

view this post on Zulip Joshua Nelson (Nov 26 2020 at 20:50):

see vaguely around https://rust-lang.zulipchat.com/#narrow/stream/122651-general/topic/broken.20rust.20docs.20links

view this post on Zulip Joshua Nelson (Nov 26 2020 at 20:51):

and https://discord.com/channels/442252698964721669/459149231702278154/773488567602249768

view this post on Zulip Noah Lev (Nov 26 2020 at 20:52):

Well I guess if it would mean I wouldn't have to rebuild rustc as much, I would feel better about moving into a separate repo. As long as it's still easy to change rustdoc from rust-lang/rust in case compiler changes are needed.

view this post on Zulip Poliorcetics (Nov 26 2020 at 20:52):

The main complaint on rustdoc being in-tree is that ./x.py build is very long the first time, which, for new contributors, is not very engaging (+ they have to discover ./x.py too, which can be long and lead to horrible compile times if mishandled)

view this post on Zulip Noah Lev (Nov 26 2020 at 20:52):

But also it might be annoying if you are working on a PR and then realize you need to change the compiler and have to reapply your work on top of rust-lang/rust

view this post on Zulip Noah Lev (Nov 26 2020 at 20:53):

At this point, x.py should be pretty easy for basic rustdoc things though. All you do is ./x.py build and ./x.py test src/test/rustdoc

view this post on Zulip Noah Lev (Nov 26 2020 at 20:53):

As long as we don't have any of that ./x.py build --stage 1 --keep-stage 0 advice left

view this post on Zulip Noah Lev (Nov 26 2020 at 20:54):

(Oh, I'm so glad we can finally talk on Zulip :pray:)

view this post on Zulip Poliorcetics (Nov 26 2020 at 20:54):

Camelid said:

At this point, x.py should be pretty easy for basic rustdoc things though. All you do is ./x.py build and ./x.py test src/test/rustdoc

That has to be discovered and the first ./x.py build is lonngggggg (especially for people without CI-llvm)

view this post on Zulip Poliorcetics (Nov 26 2020 at 20:54):

After that though, the experience is quite nice IMO

view this post on Zulip Joshua Nelson (Nov 26 2020 at 20:58):

So it sounds like we should try rustup-toolchain-install-master in-tree and see how that goes

view this post on Zulip Joshua Nelson (Nov 26 2020 at 20:59):

And then we can separate the awful compile times from building in-tree vs out of tree

view this post on Zulip Joshua Nelson (Nov 26 2020 at 21:00):

The only issue I see is there will be two different ways to build rustdoc now: one with x.py and one with a recent nightly; we need a way to teach it

view this post on Zulip Poliorcetics (Nov 26 2020 at 21:03):

Is there a precedent for a ./x.py rustdoc command that would call rustup-toolchain-install-master ?

view this post on Zulip Poliorcetics (Nov 26 2020 at 21:04):

That way people can still use x.py without having to worry about 2 build systems

view this post on Zulip Joshua Nelson (Nov 26 2020 at 21:21):

Well that's still two different build systems, they're just using the same command

view this post on Zulip Joshua Nelson (Nov 26 2020 at 21:21):

And they fundamentally need to be different build systems or you won't be able to make changes to rustc and rustdoc at the same time

view this post on Zulip Noah Lev (Nov 26 2020 at 23:11):

One of the things that I find frustrating about subtrees is cases like #79329. I need to update Clippy test output, but running ./x.py test isn't giving me enough information, so I tried cd'ing into src/tools/clippy and running cargo test, but now I'm getting an unrelated compile error (and I have no idea what's causing it):

error[E0599]: no method named `def_id` found for struct `ConstnessAnd<Binder<rustc_middle::ty::TraitRef<'_>>>` in the current scope
  --> src/tools/clippy/clippy_lints/src/future_not_send.rs:71:39
   |
71 |                     if Some(trait_ref.def_id()) == cx.tcx.lang_items().future_trait() {
   |                                       ^^^^^^ method not found in `ConstnessAnd<Binder<rustc_middle::ty::TraitRef<'_>>>`

view this post on Zulip Manish Goregaokar (Nov 26 2020 at 23:39):

GuillaumeGomez said:

Manish Goregaokar said:

with clippy it's just cargo test

With cargo too and yet you don't see huge contributions. I don't think this is where most of the newcomers difficulty is to be honest.

this is because cargo is a tricky codebase to contribute to

view this post on Zulip Manish Goregaokar (Nov 26 2020 at 23:40):

rustdoc is not that complex, but having to do a full rust build and use the rustc build system are problems

view this post on Zulip Manish Goregaokar (Nov 26 2020 at 23:40):

the main thing would be to make it easy to contribute with a preexisting rust

view this post on Zulip Manish Goregaokar (Nov 26 2020 at 23:41):

Camelid said:

One of the things that I find frustrating about subtrees is cases like #79329. I need to update Clippy test output, but running ./x.py test isn't giving me enough information, so I tried cd'ing into src/tools/clippy and running cargo test, but now I'm getting an unrelated compile error (and I have no idea what's causing it):

error[E0599]: no method named `def_id` found for struct `ConstnessAnd<Binder<rustc_middle::ty::TraitRef<'_>>>` in the current scope
  --> src/tools/clippy/clippy_lints/src/future_not_send.rs:71:39
   |
71 |                     if Some(trait_ref.def_id()) == cx.tcx.lang_items().future_trait() {
   |                                       ^^^^^^ method not found in `ConstnessAnd<Binder<rustc_middle::ty::TraitRef<'_>>>`

thta'ts because cargo test uses your installed rust and there's a rustup mismatch

view this post on Zulip Manish Goregaokar (Nov 26 2020 at 23:41):

you'd want to RTIM and then cargo +master test

view this post on Zulip Noah Lev (Nov 27 2020 at 01:16):

Ah, that makes sense. But this is kind of my point: using subtrees means there are more ways to build and thus more things that you need to know.

view this post on Zulip Noah Lev (Nov 27 2020 at 01:17):

Though this conversation should be probably be moved to "Building rustdoc out of tree" or a new topic :sweat_smile:

view this post on Zulip apiraino (Dec 14 2020 at 11:48):

@GuillaumeGomez @Joshua Nelson just to complement the contact points in the blog post (going to publish the draft right now). I'll be mentioning:

my question is, what about the #docs channel on Discord (also quite active)? Looks like a channel for helping people using and building rust documentation, correct?

view this post on Zulip GuillaumeGomez (Dec 14 2020 at 12:14):

It's the channel for the (now removed) doc team, not rustdoc. ;)

view this post on Zulip GuillaumeGomez (Dec 14 2020 at 12:14):

But yes, zulip as preferred way and discord as backup seems fine :)

view this post on Zulip Noah Lev (Dec 14 2020 at 19:59):

Technically, T-doc is still around, but I have a PR to finally archive it: rust-lang/team#487 :)

view this post on Zulip Nelson J Morais (Dec 21 2020 at 20:57):

Joshua Nelson said:

Nelson J Morais do you want to test it out? there are some ideas in https://github.com/rust-lang/rust/issues/66581 :smile:

it compiles

 Compiling rustdoc-tool v0.0.0 (D:\Code\rust\rust\src\tools\rustdoc)
     Running `rustc --crate-name rustdoc_tool_binary --edition=2018 main.rs --error-format=json --json=diagnostic-rendered-ansi --crate-type bin --emit=dep-info,link -C embed-bitcode=no -C debuginfo=2 -C metadata=fa64a24d483a6a98 --out-dir D:\Code\rust\rust\src\tools\rustdoc\target\debug\deps -C incremental=D:\Code\rust\rust\src\tools\rustdoc\target\debug\incremental -L dependency=D:\Code\rust\rust\src\tools\rustdoc\target\debug\deps --extern rustdoc=D:\Code\rust\rust\src\tools\rustdoc\target\debug\deps\librustdoc-93b08559b7720bee.rlib`
    Finished dev [unoptimized + debuginfo] target(s) in 59.19s
D:\Code\rust\rust\src\tools\rustdoc(master)> .\target\debug\rustdoc_tool_binary.exe --help

but then it fails to find test-<hash>.dll, std-<hash>.dll and rustc_driver-<hash>.dll

view this post on Zulip Nelson J Morais (Dec 21 2020 at 20:58):

image.png

view this post on Zulip Nelson J Morais (Dec 21 2020 at 20:58):

can't find those anywhere :\

view this post on Zulip Joshua Nelson (Dec 21 2020 at 20:59):

that's a sysroot issue

view this post on Zulip Joshua Nelson (Dec 21 2020 at 20:59):

sorry, most of this is out of date now

view this post on Zulip Joshua Nelson (Dec 21 2020 at 20:59):

if you want to use rustdoc with a hard-coded rustc version you can try https://github.com/rust-lang/rust/commit/500b0f3c1ba651f31abc551ccbcf222f48e355a2

view this post on Zulip Joshua Nelson (Dec 21 2020 at 20:59):

see https://github.com/rust-lang/rust/pull/79540

view this post on Zulip Nelson J Morais (Dec 21 2020 at 21:11):

will try that :+1:


Last updated: Oct 11 2021 at 22:34 UTC