The Rustdoc Redux

[ssokolow]

Your viewpoint is certainly defensible.

That said, one of the strong streaks to my personality is that, if I perceive myself as being forced into a decision, my desire to resist grows to extremes which risk overruling my rational judgment. (It’s led me to do things like ripping out my apt-get update GUI and replacing it with a homegrown hack in response to the removal of the dconf key to opt out of daily “reboot to update your kernel” nags.)

I suspect I’ll wind up either writing my own rustdoc frontend or writing some kind of JSON->ReST Python script to use as an input stage for Sphinx. (The latter may even be more desirable, since it’d combine the “can’t forget to mention a function” aspect of tools like Rustdoc and ePyDoc with the ability to easily include the API docs as an appendix in a hand-written manual.)

(Well, that and I’ll probably need it to generate Rust documentation for my Zeal offline documentation viewer.)

[steveklabnik]

I think the most important thing that’s strangely absent in rustdoc is cross-referencesing.

https://github.com/rust-lang/rfcs/pull/1946

[Aankhen]

@steveklabnik, thank you very much for your work. I feel churlish saying this because there’s so much else that’s great about the rewrite, but I have to agree that it’s unfortunate that rather than moving away from the crates.io-style JS frontend, this embraces it.

JS-enhanced pages are convenient. JS-based pages create a much worse loading experience, not to mention add new failure modes that do not degrade gracefully. One network error—still an everyday occurrence around the world—and instead of a skeleton page where all the content is accessible, there’s just a blank space. Same for an error in the JavaScript itself before the content is loaded.

With reloading with CTRL+R (having a warm cache), the process from 1 to 6 takes roughly 1 second until I get the “blue” line in my network tab (the DOMContentLoaded event of the page) on my desktop machine with Firefox 54.

Indeed. Here’s the Chrome DevTools breakdown of the PyPI page for boto (a poorly-optimized static page) on my modern PC with a 10 Mbit connection:

The page is usable (see the filmstrip) at the 2-second mark. Here’s the same thing for winapi:

The page is usable (see the filmstrip) at about the 3.7-second mark. Nearly 2 seconds are spent just on executing JavaScript, which will not be solved by server push, HTTP/2, or any other protocol changes. I’d guess FastBoot would let the page load more quickly—although I assume there’s an impact on the server’s response time—but if you still need to download and run the entire application on the client at the end of it…

Using a static page generator for this would still require a great deal of JavaScript to make it work. At some point doing everything in JavaScript is just easier than a mish-mash of JS and static HTML.

I’m not sure what JS is required for other than searching without reloading, although naturally there are several conveniences that it can add (and that I’m in favour of). HTML5 and CSS3 together give us so much that we’re used to reinventing poorly in JavaScript, but in a simple, declarative form.

[Migi]

Rustdoc does two things:

1. Read rust source code and understand it enough to extract the right data from it.
2. Display that data to the user in some way, as either plain HTML, Javascript-enhanced stuff or just plain JSON.

A lot of discussion about the second has happened already, but I’d like to talk a bit about the first. I remember a while ago that there was some talk about separating Rustdoc from rustc, and somebody suggested using RLS to do the parsing/understanding of Rust code, which made a lot of sense to me. Everything that Rustdoc wants to do, RLS wants to do too, so why not reuse RLS to do both?

It seems like the understanding of Rust that Rustdoc needs to do is fairly minimal: extract structs, traits, impls, fns and doc-comments and that’s pretty much it, so why bother using RLS? Well I think Rustdoc may in the future do more advanced things, like say you have a struct with a member of type SomeType, then that SomeType could be a clickable link to the definition of SomeType. This is almost exactly like what “jump to definition” would do in RLS, so there’s more potential for reuse there.

So, tl;dr: please consider using RLS to avoid a lot of wheel-reinventing. It would be beneficial for both Rustdoc and RLS.

[steveklabnik]

This is exactly what we’re doing: https://github.com/steveklabnik/rustdoc/blob/master/Cargo.toml#L12

[ssokolow]

Thank you for stating so eloquently what I was reaching for and falling far short of.

[carols10cents]

Nearly 2 seconds are spent just on executing JavaScript, which will not be solved by server push, HTTP/2, or any other protocol changes. I’d guess FastBoot would let the page load more quickly—although I assume there’s an impact on the server’s response time—but if you still need to download and run the entire application on the client at the end of it…

We know Crates.io’s performance isn’t great, and we’re working on fastboot support. When that’s done, we will profile again and continue to adjust. Posting more network graphs isn’t giving us any information we don’t already know about, nor will it change the priorities of what people are working on. If you’d like to help, we’d love your pull requests, that would be much more constructive.

[Migi]

That’s great to hear then!

I’ll try to help out a bit if I can.

[ssokolow]

We know Crates.io’s performance isn’t great, and we’re working on fastboot support. When that’s done, we will profile again and continue to adjust. Posting more network graphs isn’t giving us any information we don’t already know about, nor will it change the priorities of what people are working on. If you’d like to help, we’d love your pull requests, that would be much more constructive.

While most of that post was network graphs and the associated text, I just want to make sure that these much smaller bits don’t get overlooked or forgotten:

JS-enhanced pages are convenient. JS-based pages create a much worse loading experience, not to mention add new failure modes that do not degrade gracefully. One network error—still an everyday occurrence around the world—and instead of a skeleton page where all the content is accessible, there’s just a blank space. Same for an error in the JavaScript itself before the content is loaded.

I have to agree with people like Rob Larsen (You’re So Smart You Turned JavaScript into xHTML) who say this is a lesser version of the very problem which prevented “XHTML parsed as XML” from catching on.

I’ve run into this problem myself on occasion and DSL in Canada isn’t exactly of “developing nation” quality. It’s annoying and, just as like the engineered delays and errors created by the Great Firewall of China, that irritation gets directed at the site I’m trying to visit, regardless of its source.

I’m not sure what JS is required for other than searching without reloading, although naturally there are several conveniences that it can add (and that I’m in favour of). HTML5 and CSS3 together give us so much that we’re used to reinventing poorly in JavaScript, but in a simple, declarative form.

Here, I can’t help but be reminded of pieces by Christian Heilmann like Web bloat isn’t a knowledge problem and Breaking out of the Tetris mindset.

…or CSS vs. JavaScript: Trust vs. Control. If you replace CSS with HTML, most of the arguments based on abstract claims still hold up just as well (fault-tolerant, browsers in constrained environments can decide to sacrifice fidelity for performance, etc.)

[birkenfeld]

Posting more network graphs isn’t giving us any information we don’t already know about

However it gives other people, who haven’t profiled crates.io, but would like to follow this discussion, some background, which is pretty constructive in my book. “PR or shut up” isn’t something I thought the Rust community practices.

[carols10cents]

I just want to make sure that these much smaller bits don’t get overlooked or forgotten:

I’d just like to make sure this smaller bit doesn’t get overlooked or forgotten:

If you’d like to help, we’d love your pull requests, that would be much more constructive.

Please file issues and send in PRs for these problems.

[carols10cents]

However it gives other people, who haven’t profiled crates.io, but would like to follow this discussion, some background, which is pretty constructive in my book. “PR or shut up” isn’t something I thought the Rust community practices.

Criticizing without offering help (and help definitely includes filing issues where we track work) is not constructive, no. I don’t see how making the same criticism repeatedly in the same thread is useful in giving other people more background. It’s just piling on.

[Aankhen]

We know Crates.io’s performance isn’t great, and we’re working on fastboot support. When that’s done, we will profile again and continue to adjust. Posting more network graphs isn’t giving us any information we don’t already know about, nor will it change the priorities of what people are working on.

I’m sorry if it came across as me saying crates.io doesn’t work well or demanding improvements. That was not my intention. I brought it up in this context because to me the problem with crates.io seems to be the fact that its frontend is built entirely in JS, which it appears is the plan for rustdoc redux too.

Yes, you can absolutely build performant, fault-tolerant (to some extent), and—as you mentioned earlier in the thread—accessible frontends entirely in JavaScript, just as you can write memory-safe code in C.

If you’d like to help, we’d love your pull requests, that would be much more constructive.

As it happens, for the past few weeks I’ve been trying to find some time to set up the dev environment and see what it would take to slowly convert the site to HTML with JS enhancements. Then yesterday I saw the FastBoot PR. Is the static route still something that would be useful and for which PRs would be accepted?

[ssokolow]

Ok, replying with a mimickry of my post is giving me a sense of passive-aggressive hostility here.

I don’t feel comfortable with the direction this is going, so I’m going to bow out now.

[carols10cents]

Then yesterday I saw the FastBoot PR. Is the static route still something that would be useful and for which PRs would be accepted?

We’d prefer to try FastBoot first, at this point. Again, we’ll be continually evaluating performance and acknowledge that poor performance a bug that will need time and people to fix.

[steveklabnik]

However it gives other people, who haven’t profiled crates.io, but would like to follow this discussion, some background, which is pretty constructive in my book. “PR or shut up” isn’t something I thought the Rust community practices.

It’s true that it’s not, but also, I’m not sure this is an accurate characterization, exactly. Let me back up a bit.

After thinking about this problem for months, and discussing it with many people, numerous times, I actually had a lot of anxiety about making this thread. Why? Because I knew that some people would show up and be like “using JavaScript here is bad.” Regardless of the actual merits of JavaScript. Because that’s how these kinds of discussions on the internet go.

Consider two versions of this same conversation, happening in the same thread. The first was between @whitequark and I, here: The Rustdoc Redux

The general format is: “I have this concern.” “I hear your concern, and I believe I will address your concerns.” “Okay, that’s reassuring enough to me.”

That’s how constructive discussion works. And I do feel that I have a handle on many of the concerns in this thread, and ways to deal with them.

These later replies, however, are basically repeating the same thing. And many of them are not about rustdoc, but instead, about crates.io. Yes, they both use Ember. They’re also very different. And so basically, this discussion about rustdoc has gotten almost entirely derailed by the question “is JavaScript good or not”, which is extremely offtopic. Let me pull some quotes that I find to be quite aggressive:

I also find the claim that using Ember will not impact performance to be laughable.

This is responding to something I’ve said with no evidence. Actually, it’s not even responding to my claim; it’s technically agreeing with me, though that’s not what the implication was. My assertion is that I expect rustdoc’s performance to get faster, but instead this is a blanket assertion that it will be slower. Instead of digging into the technical details of why I might think that, it’s instead just generalities and an insult.

I treat such a lazy first impression (a blank page) as an indicator that a company is probably too incompetent to trust with my business.

This is calling the people who work on crates.io “incompetent.” Same as above, this is mostly a general criticism of JavaScript itself rather than specific, technical details.

(To their credit, the author did apologize later, but still)

These and other comments already set an antagonistic tone. So yes, in some ways, @carols10cents responded in kind. Maybe she (like myself) should have just stopped responding. (here I am, back again, because I care about this.) That said, I suspect part of the reason she’s reacting this way is what I started my comment out with: aggressive criticism of people’s work makes them not want to even do the work in the first place, let alone share it with others, and that’s also a problem.

The problem with the line of argument that’s been going on in this thread is basically “youre incompetent, JS is bad, please re-write an entire application to make me feel better.” And so, the natural (in some ways) response is “If you really feel like it’d be better that way, please do the work rather than just idly criticizing.” Maybe that could have been stated in a more constructive way, but this is why being aggressive in the first place doesn’t work; it makes people defensive, and then people just argue rather than getting stuff done.

Thank you for caring about standards of communication here. I wish I had said something earlier in the thread, to maybe cut this off a bit earlier.

I’m going to ignore the rest of this thread now, it’s been derailed to the point of uselessness. For those of you with crates.io concerns, please open bugs over there. For those of you with rustdoc frontend concerns, well, I believe I understand all the big-picture stuff that’s been raised in this thread, and we can have more specific discussions about the details once it actually exists.

Thanks.

[ssokolow]

And so, the natural (in some ways) response is “If you really feel like it’d be better that way, please do the work rather than just idly criticizing.”

In the interest of trying to understand how communications broke down, I’d like to mention that I came away with the impression that Ember was non-negotiable, so, despite my best efforts, my responses were coloured by a strong emotional undertone of “Fine. I still don’t have to put up with this. Once things have stabilized, I’ll write my own static generator on top of the JSON output and meet the standards for graceful degradation on my projects that way.”

(Something I still intend to do… though, given time constraints, I may just have to go with the “script a quick-and-dirty rustdoc JSON input plugin for Sphinx” possibility I mentioned.)

[matthall]

Consider two versions of this same conversation, happening in the same thread. The first was between @whitequark and I, here: The Rustdoc Redux The general format is: “I have this concern.” “I hear your concern, and I believe I will address your concerns.” “Okay, that’s reassuring enough to me.”

I’m not sure if “you can write your own frontend” is really addressing the concert - certainly for a lot of people it won’t be. If the ember frontend is what ends up running on doc.rust-lang.org or docs.rs and it does have poor performance (even slightly poorer performance that currently) that’s making the experience of a tonne of people worse.

I’d also argue that the other replies aren’t about whether JS is good or not, it’s very much whether an entirely JS app is justified in this situation. No one is disagreeing that the search and folding of methods currently is a bad thing.

JS is bad, please re-write an entire application to make me feel better

Really it has been: please don’t rewrite rustdoc like this. Rustdoc isn’t written in ember currently.

[ahmedcharles]

My interpretation of the feedback is effectively represented by this timeline:

0. Rustdoc exists as a tool which converts rust code into documentation. The format of that documentation and it’s stability are debatable, but most users view it to be stable enough, in the ways that they care about.
1. Some potential contributors to rustdoc find it hard to get involved because rustdoc is tightly coupled to the compiler code base.
2. The maintainers of rustdoc decide to rewrite rustdoc for various reasons, one of which being to help potential contributors get involved.
3. As part of the rewrite, the maintainers decide to change the format of the output documentation.
4. The maintainers announce the rewrite.
5. Some people notice that the format of the documentation will change in a way that they care about and they express this.

So, if this timeline is right, it seems that the issue is that if you’re motivated to rewrite something in order to increase the potential pool of contributors, that rewrite should not include a seemingly unrelated change to the format of the input or output of the program, at least without being appropriately motivated. And in the context of Rust and it’s desire to be stable, I would’ve thought that this sort of change would’ve been more explicitly motivated.

It doesn’t really seem to have anything to do with javascript or it being bad and everything to do with the sudden realization that a tool is going to have it’s output changed in a significant way that impacts people in the community.

Though, pragmatically, if frontends really are pluggable, why not write a frontend which produces byte compatible output with current rustdoc and have the improved frontend be an option for those who want the improved docs? That would allow the market to decide which is preferred.

[sanxiyn]

I am interested in working on “rustdoc-classic”, working name, re-using new RLS framework instead of compiler internals, but producing the same output as current rustdoc. If you are interested, you can mail me at sanxiyn@gmail.com.

I actually hope rustdoc-classic to replace rustdoc-redux, but I am not sure whether such effort would be considered for merging.