Rustdoc: Ideas

#1

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.

  1. 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.

  2. 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.

  3. 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 :slight_smile: 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.

c3aed0f24298019d.png2870×1202

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.

#2

Related to the “presentation is ineffective” point, I’d really like to see this issue get fixed. It takes way longer than it needs to to find the name of the method you’re looking through full method descriptions and examples. A simple list of all function signatures at the top would be useful for identifying the functions you need.

#3

Rustdoc is able to collapse descriptions now, so you should already be able to get that.

#4

Thanks, that’s pretty helpful. Another suggestion about organization would be alphabetizing method names, so searching for methods is easier.

#5

On a slightly related note, there appears to be an ongoing effort to standarize markdown with at least Github and Discourse involved: two systems Rust also uses. Ensuring Rustdoc uses Standard Flavoured Markdown may be useful. Note that I am not well versed in the differences, or indeed what Rustdoc uses now.

#6

I’m not sure I would want this by default, but it might be interesting as a client-side button. Currently the (non-trait) methods are sorted by the order they’re found in the source, as far as I know. This can theoretically produce a “natural” grouping of methods, but obviously it isn’t always the right one.

Other interesting sorts/filters might be safe/unsafe and static/&self/&mut-self/self.

#7

@thehydroimpulse I’ve been mulling over some extensions to my collapsable work, but I’m uncertain whether your planned work would completely clobber all of that. Any status updates?

#8

@Gankro I just got an initial version implemented locally in rustdoc. I started cutting a lot of the old html, old css, etc… and cleaning up rustdoc a bit. Right now I’m focused on getting different rendering support separate from any design change to make it easier to land (without too much fuss). So being able to render plain text, man page, etc… to be used within vim et al.

I’d say go ahead with your extensions for the time being. I’ll probably get an early version of my redesign posted here in the next week or so.

That being said, I’m actually integrating your collapsed work into my design in multiple ways.