Rust: Unstable book is a serious contribution speed bump

[nagisa]

Every time I make a PR, I always get hit by the unstable book tidy check. It always takes me at least 3 roundtrips until I get it right. I hate it (the book) very much at this point.

IMO the process is unnecessarily complicated. Especially so, given that the fix usually ends up being just a link to the tracking issue – information already available to the compiler in the attribute.

I propose that the book would not require adding a link like that for every single feature and instead the pages with links to a tracking issue were generated automatically, during the generation of the book.

I do not the benefits provided by the book warrant making the contribution process so much more complicated.

[Mark-Simulacrum]

I actually think the underlying problem here is different: there is little to no point in having an unstable book if we don't utilize it to document these features. While these features are somewhat in flux due to their nature of instability, we should still document them. As such, I don't think we should auto-generate the book, though we should consider making it easier to get the initial template up for the PR author to add to as they're implementing the feature. I worry that if we auto-generate book pages then we'll end up always doing that, making the book almost useless -- something that I at least want to avoid. I've already expected to find documentation in the unstable book and been foiled more than once when trying to use an unstable feature.

cc @chriskrycho @rust-lang/docs

[nagisa]

@Mark-Simulacrum does it matter that much for library features though? Library functions already get their documentation in the… documentation. There’s no benefit whatsoever in copying the library documentation into a book of some sort.

[Mark-Simulacrum]

I'm not sure if we need unstable book documentation for library features, in fact I think we don't want that. I was more thinking of language features; if we currently require unstable book documentation for library features then I think we shouldn't do that (there's no point, as you've said) but should for language features. Things like catch expressions are (to my knowledge) documented effectively nowhere (except maybe in an RFC, where users don't have easy access); while I agree that the first place people land for library features is in the documentation for the standard library.

[frewsxcv]

There’s no benefit whatsoever in copying the library documentation into a book of some sort.

In my opinion, ideally, it'd be cool if each of the library features mentioned in the unstable book had links to all of the unstable APIs in the std docs since for one feature, there could be many unstable APIs.

[est31]

Re library features, I whole heartedly agree that their addition to the unstable should be automated during build time. See #41288

As for the lang features that only have stubs, we can simply autogenerate the stub, also at build time. Then no actual change of the unstable book is required.

[steveklabnik]

It always takes me at least 3 roundtrips until I get it right.

Which parts do you struggle with? From my perspective, it should be "copy over an existing one and change some numbers", so knowing what the actual trouble is here should be useful.

There’s no benefit whatsoever in copying the library documentation into a book of some sort.

One of the purposes of the Unstable Book is to show an overview of everything that exists and is unstable, so having something there is important, but I agree that duplicating it isn't particularly worthwhile. I mean, it'd be okay for browsing, but isn't a big deal, IMO.

In my opinion, ideally, it'd be cool if each of the library features mentioned in the unstable book had links to all of the unstable APIs in the std docs since for one feature, there could be many unstable APIs.

Yes, this is more useful.

[nagisa]

Which parts do you struggle with? From my perspective, it should be "copy over an existing one and change some numbers", so knowing what the actual trouble is here should be useful.

For me it usually goes like this:

• Forget it exists altogether (who bothers running the full test suite (including tidy) anyway? For tiny additions?);
• Be “smart” and do something that’s not necessarily copy-paste;
• Do the copy-paste.

[est31]

I've opened #42612 to autogenerate stubs for unstable features.