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!
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.
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
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
rustdocshould be easy to contribute to, and maintain generally
rustdocshould 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
Anyway, it’s very early days for this work. Here’s two screenshots from today:
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:
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!