come work on rustdoc!

To participate in the Rust core team’s “impl period”, i’m helping out by organizing for contributions to rustdoc, the first-party documentation generator!

Before i get too far, i want to point out some behind-the-scenes info. “rustdoc” actually refers to two projects now. Steve Klabnik has been working on a separate project that is intended to replace the current rustdoc. That project is also soliciting contributions! However, i’m not heading that up; check out the CONTRIBUTING.md file in that repo for more information.

What i’m concerned with is the rustdoc that currently ships with the rust distribution, the one that’s found in the compiler’s repo. I’ve written a general overview of it before, which includes some specific tips to build and run it yourself. If you’re interested in how it works, definitely check that out.

However, one thing i don’t mention in there is that there are a lot of outstanding bug reports and feature requests for rustdoc. Being almost as old as the compiler itself, and a tool that ships with every Rust install, it’s had a lot of opportunities for people to find its shortcomings. Some of these only require printing information that rustdoc already has, while some require more information to be loaded, or some change farther upstream in the compiler itself. Most of the time, though, a change just needs someone to put in the legwork necessary to plug one part to another.

That’s where you come in! I’ve started assembling a list of outstanding issues based on what kind of effort i think they’d take. It’s nowhere near complete, but it’s a good view of the first 25% of the current issues. I’ll try to add to this over time, as i get more opportunities to perform triage. The listing there categorizes issues based on whether i felt they needed significant structural work, or consensus-building, or just some time by someone who knows (or has been shown, *wink*) the layout of the code.

I would love to see this list of issues get cut down over the next few months, and i would be elated to pull in people who are interested in making the docs the best they can be. rustdoc just needs some love, would you like to help out?

If that sounds like something you’d like to get involved with, i’ve joined with the rest of the impl period working groups to have our own Gitter channel and a planning document to round up the work and chart out milestones along the way. The work is basically “cut down the A-rustdoc issue backlog”, and i’m willing to mentor and organize to help people who have never worked with the rust compiler repo get involved. Over time, i’d like to pick out issues with the least implementation effort, but for now, you can scan through the central list of all A-rustdoc issues and pick one out that you’d like to see added. I can give it a look and see what bits of rustdoc need to get messed with for it.

In the interests of having a concise guide for getting set up, here’s the basic steps to getting into the codebase. It’s… not the most simple thing, but i hope i can at least provide a quick reference for people to get started.