I’ve been working on getting rustdoc to a better state than it currently is. I’ll first explain what I think are wrong/missing from the current documentation tools.
-
Curated docs and generated docs are completely separate. This means widely different designs and feature sets. The current curated documentation system is greatly in need of some work instead of the ad-hoc “guide” system that we currently have in place. I had initially put a PR up for some early feedback in such a system (https://github.com/rust-lang/rust/pull/14245), although it was bringing in dependencies like Ruby and Bundler which weren’t appropriate. It also fractured the use of rustdoc.
-
The presentation is greatly ineffective for the generated API docs. It’s not something I like to go look at (although better than before), it seems super ad-hoc, no clear design vision nor user experience vision for that matter. API docs should be super clear and understandable. Pros should also have more visibility than currently.
-
Rustdoc currently outputs ugly HTML, but this is rather an implementation detail and fairly trivial to improve.
I believe we need rustdoc to be in a much better state before people start flocking to it. Having kick-ass documentation (not just in terms of content – which we got covered but also in terms of presentation and tooling). Right now, projects can only really use the generated doc feature of rustdoc, so curated documentation won’t be promoted as heavily and projects would have to either individually setup their own, or have it in a github Readme.
I’m proposing a single documentation solution that will merge curated docs and generated docs into a single thing. This would essentially allow projects to get up extremely quickly with top notch documentation that they won’t have to worry about.
It’s still fairly early but I thought I’d get it out earlier than later. If you would click on the Gossip
crate, the sidebar would then contain Modules
, Functions
, etc… instead of the Crates
section. However, for every item, you have the Docs
section that show a high priority in showing pros. Because, for newcomers, it can be quite frustrating just having an API signature and perhaps an example.
Still got a while to go to reach a PR.