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.

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 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:

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

should be easy to contribute to, and maintain generally rustdoc should be easier to customize

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:

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:

GitHub 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!