# The Rustdoc Redux **URL:** \ **Category:** announcements\ **Created:** [July 14, 2017, 3:13pm UTC](https://internals.rust-lang.org/t/the-rustdoc-redux/5542 "2017-07-14T15:13:40Z")\ **Posts on this page:** 20\ **Page:** 1
**Author:** ![steveklabnik](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/steveklabnik/32/4524_2.png) [@steveklabnik](https://internals.rust-lang.org/u/steveklabnik)\ **Post date:** [July 14, 2017, 3:13pm UTC](https://internals.rust-lang.org/t/the-rustdoc-redux/5542/1 "2017-07-14T15:13:40Z")
Hey all, `rustdoc` is a wonderful tool for Rust developers, giving us the ability to write great docs for our code. In a recent survey of Rust developers, [good docs were the #1 thing people looked for when choosing a dependency](https://github.com/rust-lang/rfcs/blob/master/text/1824-crates.io-default-ranking.md#factors-considered-when-ranking-crates). `rustdoc` has a long and venerable history in Rust; it was first added in 2011, making it almost six years old! > However, `rustdoc` is tough to contribute to, as it uses the compiler's guts to generate the docs. This means that, if you want to change one line of rustdoc's CSS, you must first bootstrap the entire compiler, including building LLVM. It's... not pleasant. For more on how Rustdoc works, see [this great post](https://quietmisdreavus.net/code/2017/06/21/a-whirlwind-tour-of-rustdoc/) by docs team member @QuietMisdreavus. Because `rustdoc` is so hard to contribute to, it rarely gets worked on. People like @alexcrichton just before 1.0 and @GuillaumeGomez and @ollie27 today (among others) have done some heroic work making `rustdoc` better, but very few people _enjoy_ working on `rustdoc`. As such, bugs pretty much don't get fixed: ![](https://us1.discourse-cdn.com/flex002/uploads/rustlang/original/2X/8/88d38a1a45bc3ebf5effad36ab8eb43360a34cdc.png) `A-diagnostics` is the only tag that's got more bugs than `A-rustdoc`. * * * So, what to do? Over the last year, (usually after having one too many 🍻) I get mad at `rustdoc` and threaten to re-write it. I've even hacked together multiple prototypes. Now that the end of the book v2 work is in sight, I'm going to be doing more work on the tooling we have for docs. `rustdoc` is target number one, as it's the foundation of everything else. After long discussions with members of the dev-tools and compiler teams, and some thoughts out how to improve `rustdoc`, I am happy to announce that I'm working on a replacement for `rustdoc`. It's a ground-up re-write. Normally I'd be hesitant to go for a re-write, but after long discussions, the fundamental architecture of how `rustdoc` works needs to be re-done, and so a refactoring would be tantamount to a re-write anyway. Some goals for the `rustdoc` redux: - `rustdoc` should be easy to contribute to, and maintain generally - `rustdoc` should be easier to customize - long-standing bugs should be fixed - Be good for more than API docs, like guides These high-level goals imply many other things. For example, making `rustdoc` easy to contribute to means "you should not need to build the compiler to build `rustdoc`." Anyway, it's very early days for this work. Here's two screenshots from today: ![](https://us1.discourse-cdn.com/flex002/uploads/rustlang/original/2X/c/c50a49c26c9ea6b14d480603f4051a2f6ef3eba3.png) ![](https://us1.discourse-cdn.com/flex002/uploads/rustlang/original/2X/3/30aa91f14769eb176fae855261b297638e15dbdb.png) Rustdoc can currently get your crate docs, the list of top-level modules, and their docs. That's it. There's no CSS, even! However, the core of it is there: take Rust code, produce HTML, CSS, and JavaScript. There's a lot of work left to do, and so, if you're interested, I'd love some help! This is a great way to get started working on a Rust project, even if you haven't done much Rust before. There's a lot going on: Rust code, JSON generation, working with web technologies, re-thinking the presentation, all kinds of stuff. Heck, you can work on the front-end without even installing Rust! Since it's so early on, you have the chance to make _significant_ contribution to a tool that every single Rust developer uses. I'd love to form a little team around `rustdoc` and make it amazing. The repository is here: > **[steveklabnik/rustdoc](https://github.com/steveklabnik/rustdoc)** > > Not a real thing, see https://github.com/rust-lang/rust for rustdoc's actual source code - steveklabnik/rustdoc Check out the issue tracker; I've made a number of issues already, but am going to be making more throughout today. Several of them will be "discussion" style issues to work up ideas, so if you're not interested in writing code, you may want to get involved in those discussions! Thanks! ---
**Author:** ![est31](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/est31/32/2551_2.png) [@est31](https://internals.rust-lang.org/u/est31)\ **Post date:** [July 14, 2017, 3:39pm UTC](https://internals.rust-lang.org/t/the-rustdoc-redux/5542/2 "2017-07-14T15:39:59Z")
Congratulations to the announcement! My personal wishlist for the rustdoc rewrite: - Creating docs even if there is a compiler error. This would probably also be needed by RLS. - Reconsidering to add [KaTex support](https://github.com/rust-lang/rust/issues/16300) - Not regressing on performance. Right now it seems to be implemented in ember. When visiting [crates.io](http://crates.io) (even with latest firefox nightly with webrender enabled, which is supposed to be and actually is blazingly fast) clicking on every link first greets me with a “loading” page and only then the actual page builds up. Sometimes stuff is cached, but most times I get the loading page. I’m not a web dev, so maybe I just don’t recognize wanted behaviour here, but to me it feels like a bug. Its pretty annoying at the least. I understand that [crates.io](http://crates.io) had to ship with the bug as it was new, but its different (I think?) with rustdoc, as there is time and already a mostly okay base. Not sure if the bug applies to rustdoc as well, but if it does, maybe we could wait with the switch to the new rustdoc until it has fixed the bug (maybe fastboot could do it)? - Not regressing on search-by-url. I have a firefox search keyword for searching in Rust’s std docs, would be cool if I could continue to use it. - Maybe also not breaking the URLs. To me personally its not a big issue, as I can manage to wiggle through, but I think it makes a bad image for rust if someone googles stuff and clicks an official link only to be greeted by a 404 page. ---
**Author:** ![whitequark](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/whitequark/32/12256_2.png) [@whitequark](https://internals.rust-lang.org/u/whitequark)\ **Post date:** [July 14, 2017, 3:53pm UTC](https://internals.rust-lang.org/t/the-rustdoc-redux/5542/3 "2017-07-14T15:53:27Z")
Please please _please_ don’t make JavaScript a hard dependency of rustdoc (or if that happens I hope at least the old rustdoc will be available in some form). The existing output is _great_. It has never once lagged or crashed my browser. I dread the moment I see the [doc.rust-lang.org](http://doc.rust-lang.org) tab eating hundreds of megabytes of RAM, spinning my CPU and crashing my browser, just like Discourse, Twitter, Slack, and innumerable other “web applications”. ---
**Author:** ![steveklabnik](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/steveklabnik/32/4524_2.png) [@steveklabnik](https://internals.rust-lang.org/u/steveklabnik)\ **Post date:** [July 14, 2017, 3:56pm UTC](https://internals.rust-lang.org/t/the-rustdoc-redux/5542/4 "2017-07-14T15:56:00Z")
None of those things are inherent to JavaScript; `rustdoc` today actually already uses a lot of JavaScript. No JS at all would regress many significant features. I expect it to be smaller and faster than today. And, for people who _extremely_ hate JavaScript of any kind, that’s why pluggable frontends exist; you can totally do that if you’d like. ---
**Author:** ![whitequark](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/whitequark/32/12256_2.png) [@whitequark](https://internals.rust-lang.org/u/whitequark)\ **Post date:** [July 14, 2017, 3:57pm UTC](https://internals.rust-lang.org/t/the-rustdoc-redux/5542/5 "2017-07-14T15:57:43Z")
> [@steveklabnik](#): > > And, for people who extremely hate JavaScript of any kind, that's why pluggable frontends exist; you can totally do that if you'd like. Okay, that's reassuring enough to me. ---
**Author:** ![heartsucker](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/heartsucker/32/2424_2.png) [@heartsucker](https://internals.rust-lang.org/u/heartsucker)\ **Post date:** [July 14, 2017, 3:58pm UTC](https://internals.rust-lang.org/t/the-rustdoc-redux/5542/6 "2017-07-14T15:58:50Z")
> [@steveklabnik](#): > > that's why pluggable frontends exist; you can totally do that if you'd like. Yeah, but I use NoScript, and I'd like this to mostly work out of the box. I know search won't work without JS, but I can live with that. As an end user (and not contributor), I'd like to see this use the least amount of JS possible. ---
**Author:** ![steveklabnik](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/steveklabnik/32/4524_2.png) [@steveklabnik](https://internals.rust-lang.org/u/steveklabnik)\ **Post date:** [July 14, 2017, 3:59pm UTC](https://internals.rust-lang.org/t/the-rustdoc-redux/5542/7 "2017-07-14T15:59:48Z")
All of these things are either do-able or planned: - For KaTex, historically we’ve rejected it because it adds to much overhead to those who don’t use it, but I think we can do it via a flag. - Not regressing on performance is important to me; I expect this to speed it up. - “search-by-url” isn’t a term I’m familiar with, I _think_ I know what you mean here, but if you’ve got a link or something, that’d be 👍. If it’s what I think it is, no plans to break it. - Yeah, URL compatibility is important; right now, there’s no active plans to change the URL structure. ---
**Author:** ![QuietMisdreavus](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/quietmisdreavus/32/2425_2.png) [@QuietMisdreavus](https://internals.rust-lang.org/u/QuietMisdreavus)\ **Post date:** [July 14, 2017, 4:05pm UTC](https://internals.rust-lang.org/t/the-rustdoc-redux/5542/8 "2017-07-14T16:05:15Z")
Also note that when you see the “Loading” page on [crates.io](http://crates.io), Ember’s already fully loaded. The loading you see is the page contacting the [crates.io](http://crates.io) API to load crate information. ---
**Author:** ![QuietMisdreavus](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/quietmisdreavus/32/2425_2.png) [@QuietMisdreavus](https://internals.rust-lang.org/u/QuietMisdreavus)\ **Post date:** [July 14, 2017, 4:15pm UTC](https://internals.rust-lang.org/t/the-rustdoc-redux/5542/9 "2017-07-14T16:15:25Z")
For “search-by-url”: basically, you can take a url stem and finish it with an arbitrary query to make a valid search. For example, right now you can search the stable std docs by taking the stem `https://doc.rust-lang.org/std/?search=` and appending whatever query you want on the end, like `btreeset` or the like. That will take you immediately to the search results without having to navigate to the page first. Firefox custom search providers and DuckDuckGo’s !bangs work like this. ---
**Author:** ![steveklabnik](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/steveklabnik/32/4524_2.png) [@steveklabnik](https://internals.rust-lang.org/u/steveklabnik)\ **Post date:** [July 14, 2017, 4:16pm UTC](https://internals.rust-lang.org/t/the-rustdoc-redux/5542/10 "2017-07-14T16:16:06Z")
That’s what I thought, I just hadn’t heard that term specifically used. Yeah, keeping this is 💯 ---
**Author:** ![coder543](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/coder543/32/2888_2.png) [@coder543](https://internals.rust-lang.org/u/coder543)\ **Post date:** [July 14, 2017, 4:26pm UTC](https://internals.rust-lang.org/t/the-rustdoc-redux/5542/11 "2017-07-14T16:26:10Z")
Frontend JavaScript is great, and improves the experience. I know you’re using EmberJS, but I’m not familiar with Ember. It’s in the folder labeled frontend, but the instructions on your GitHub repo specifically reference `npm` and some other things, which makes me wonder why it requires node… if it runs in the browser. All I’m concerned about is whether `rustup` is going to require `node` to be installed on every computer that wants to do Rust development and view docs. That would be hard to accept. If `node` is just required for _developing_ on `rustdoc` itself, I don’t have even the slightest issue with that. ---
**Author:** ![steveklabnik](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/steveklabnik/32/4524_2.png) [@steveklabnik](https://internals.rust-lang.org/u/steveklabnik)\ **Post date:** [July 14, 2017, 4:28pm UTC](https://internals.rust-lang.org/t/the-rustdoc-redux/5542/12 "2017-07-14T16:28:26Z")
> [@coder543](#): > > If node is just required for developing on rustdoc itself, I don't have even the slightest issue with that. Node is basically a build tool here; it's not even a requirement for developing `rustdoc`, it's a requirement only if you're working on the rustdoc frontend. If you only want to work on the backend, you don't need any of that installed, and if you're using `rustdoc`, there's no dynamic dependencies at all; the HTML/CSS/JS files are built into the binary. I certainly don't want people to depend on node to be able to read docs. ---
**Author:** ![zackw](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/zackw/32/2071_2.png) [@zackw](https://internals.rust-lang.org/u/zackw)\ **Post date:** [July 14, 2017, 4:39pm UTC](https://internals.rust-lang.org/t/the-rustdoc-redux/5542/13 "2017-07-14T16:39:27Z")
> [@steveklabnik](#): > > [Node.js is] a requirement only if you're working on the rustdoc frontend. If you only want to work on the backend, you don't need any of that installed, Could you clarify what you mean by "frontend" and "backend" in this context? For a tool like this I would expect the "frontend" to be the code that extracts documentation from .rs files, and the "backend" to be the code responsible for emitting HTML, but that doesn't jibe with what you said. ---
**Author:** ![NfNitLoop](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/nfnitloop/32/9099_2.png) [@NfNitLoop](https://internals.rust-lang.org/u/NfNitLoop)\ **Post date:** [July 14, 2017, 4:41pm UTC](https://internals.rust-lang.org/t/the-rustdoc-redux/5542/14 "2017-07-14T16:41:18Z")
“Front-end” is typically what the user sees. (here: HTML/JS in your browser) back-end is stuff that shuffles around data. (Typically on the server. But in this case it’s just being handled by the rustdoc binary.) ---
**Author:** ![steveklabnik](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/steveklabnik/32/4524_2.png) [@steveklabnik](https://internals.rust-lang.org/u/steveklabnik)\ **Post date:** [July 14, 2017, 4:41pm UTC](https://internals.rust-lang.org/t/the-rustdoc-redux/5542/15 "2017-07-14T16:41:33Z")
> [@zackw](#): > > Could you clarify what you mean by "frontend" and "backend" in this context? By "frontend" I mean "the HTML, CSS, and JavaScript", and by "backend" I mean "The Rust code that grabs all of the doc comments out of your code, generates some JSON, and writes out all of the files." ---
**Author:** ![tinaun](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/tinaun/32/169_2.png) [@tinaun](https://internals.rust-lang.org/u/tinaun)\ **Post date:** [July 14, 2017, 5:46pm UTC](https://internals.rust-lang.org/t/the-rustdoc-redux/5542/16 "2017-07-14T17:46:43Z")
yay! im glad this is being worked on. i’ve known more than one person who have bounced off rust specifically because the std docs were overwhelming. I definitely think traits and trait-derived methods could be a lot better presented then they are now, for one thing. ---
**Author:** ![steveklabnik](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/steveklabnik/32/4524_2.png) [@steveklabnik](https://internals.rust-lang.org/u/steveklabnik)\ **Post date:** [July 14, 2017, 5:48pm UTC](https://internals.rust-lang.org/t/the-rustdoc-redux/5542/17 "2017-07-14T17:48:43Z")
> [@tinaun](#): > > I definitely think traits and trait-derived methods could be a lot better presented then they are now, for one thing. If you have concrete thoughts on a better presentation, I am all ears! Please don't hesitate to open an issue. ---
**Author:** ![kornel](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/kornel/32/2711_2.png) [@kornel](https://internals.rust-lang.org/u/kornel)\ **Post date:** [July 14, 2017, 5:56pm UTC](https://internals.rust-lang.org/t/the-rustdoc-redux/5542/18 "2017-07-14T17:56:22Z")
Please, don’t make it a tool that outputs HTML or any front-end code! Make it a tool that outputs machine-readable documentation, so that others can build various documentation-related tools on top of it. ---
**Author:** ![steveklabnik](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/steveklabnik/32/4524_2.png) [@steveklabnik](https://internals.rust-lang.org/u/steveklabnik)\ **Post date:** [July 14, 2017, 5:57pm UTC](https://internals.rust-lang.org/t/the-rustdoc-redux/5542/19 "2017-07-14T17:57:34Z")
Again, that’s the default output. You can already request only JSON ([oops not quite _only_ JSON yet, but you do get it](https://github.com/steveklabnik/rustdoc/issues/27)), which is machine readable and lets other people build other tools on top. ---
**Author:** ![euclio](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/euclio/32/4705_2.png) [@euclio](https://internals.rust-lang.org/u/euclio)\ **Post date:** [July 14, 2017, 8:53pm UTC](https://internals.rust-lang.org/t/the-rustdoc-redux/5542/20 "2017-07-14T20:53:42Z")
I tried running it on a crate of mine with a few dependencies and it took an enormous amount of time, and ended up panicking in the end. Why does the save analysis take so long? [Next page](https://internals.rust-lang.org/t/the-rustdoc-redux/5542.md?page=2)