POC of a new design for the generated rustdoc

documentation
#1

**edited for the second version **

Why ?

I do not feel at ease with the way the rustdoc generated pages are currently structured. I fell that the docs are not easy to read and navigate into, especially on types with many methods with many different implementations.

I had a few ideas on how to improve the situation, so I decided to experiment them on a tiny proof of concept, limited to two pages (HashMap and collections), demonstrating what I would like to see in the generated rustdoc.

link : https://utherii.github.io/new.html

What will I do with this?

First, I would like to know if people like my alternative design, since it changes substantially the look and the way you navigate, it may not please everybody. Then I would like to know if the rustdoc team is interested to use my ideas in rustdoc.

According to the feedback, I may work to make it part of rustdoc, work on this as a separate project or just give up the idea.

The main differences with the existing rustdoc are :

  • Compact summary at the top of the pages (with icons)
    • methods can be grouped by name or by implementation
    • method with multiple implementations are folded (useful on type like primitives)
    • tooltips displaying the full declarations of function and implementation.
  • The sidebar is resizable and contains:
    • the search bar (searches are usually small, no need for a huge bar)
    • a expandable tree view containing:
      • the markdown documentation (as first item).
      • primitives and keyword (outside of the std crate since they are not part of it).
      • the main crate and the related crates (by default the tree is open on the main crate)
    • the tree is unfold to display the current item, but you should be able to unfold the nodes manually).
  • Menubar to switch between summary, description and the methods details anytime.
  • The current implementation is stuck to the top of the page when scrolling the method description.
  • The block collapsing feature (too messy IMO) was removed

Poc limitation

  • Only two pages can be viewed: std::collection and std::collection::Hashmap
  • In the sidebar, you can only expand the book, keywords, primitives, the std crate and std::collection module.
  • Lot of functionalities missing : search, source, ... (it's just a POC)
  • The back back button isn't working well.
  • Most link are broken
  • The look and feel is not final
  • No responsive design yet (look bad on mobile).
14 Likes
#2

I do like the very-compact list of things with --oneline descriptions.

I'm not certain that alphabetical is the best option for it. Having ne and eq not be next to each other is unfortunate. That said, I don't have a concrete suggestion for you here.

nit: There's something strange going on with the "Home" key on your prototype -- it usually goes back to the top, which I used to try to get back to the list, but it didn't work, behaving more like

2 Likes
#3

What about sorting by the second column and then the first to get ne and eq next to each other?

#4

I believe alphabetical order is more convenient to find quickly what you are looking for since you usually have an idea of the name of the method while the traits have no special order.

It might be possible to add an option to switch from grouping by name, to grouping by trait.

#5

Thank you for working on this! I agree with you that there is room for improvement on rustdoc. I'm not convinced this exact design nails it though.

Things I like:

  • compactness
  • a search bar always visible. Even though with rustdoc it's only an "s" hotkey away, I have a hard time adapting to it and often have the reflex of scrolling. However I think it should be an instant "as you type" filter on the outline.
  • I do prefer an outline on the left above the sections "Modules", "Macros", "Structs", "Traits", etc of rustdoc, which don't have much informational value. However I think there is a problem in practice. Many rust libraries are organized in modules for the developer convenience, but those modules are private, and items are re-exported. That somewhat beats the point of an outline if it becomes a mostly flat list under "prelude". That being said maybe we need to see it on some crates to get a feel for it, because I think it's still nicer to see that list at the left than to have to go all the way to the bottom of a long readme to find it. In any case on the standard library a foldable outline is top! I feel like I "see" the standard library for the first time! It makes me want to browse it to discover it. Rustdoc never did that for me, thanks!
  • Inclusion of the book. It would need a good UI design, but I can totally see it being integrated in the api docs (I mean even the other books, reference, nomicon, rust by example, ...) Eg a really integrated total documentation of rust in one interface. There could be links between the api docs and guide level documentation for more examples, explanation, ... It would also be nice if crates could easily include a user guide straight in the api docs.

Things I don't like:

  • Rust being a type strict language I really want to see the declaration of the type. I think it's nice of rustdoc to show that all the way at the top. It's what I look at most.
  • Look and feel. A lot of work there, but that's ok for POC. I do like the look and feel of rustdoc + ayu-dark.
  • fluidity. On my wide screen there is a whole empty area on the right. Ideally there is a well thought out design for every level, from a phone to a 4k screen that really makes good use of all the available screen space.

Mitigated:

  • I like alphabetic sorting, but I think I would like at least a button that let's you order and group by implemented traits.
  • Not quite sure of the usefulness of the long methods tab. I think I would be more in favor of clicking in the item list folds open a section for the item, pushing escape closes it again. Btw I would do thing like links to the books in a similar way, overlay, so you can read and browse, escape it hides again and you are still in the api docs where you left of.

Ok, there is surely a lot more to say, but I'll leave that to others.

5 Likes
#6

I like the compact table at the top with all the methods and their 1-line descriptions. It gives a good overview of what the type can do. It'd be great for Option or Vec which have lots of convenience methods.

The sidebar with filesystem-like navigation seems useful too. In the current rustdoc it's confusing, because it's sometimes navigation between sibling pages, sometimes navigation within the same page, and the structure is not clear.

6 Likes
#7

Above that, I'd love to see "Trait implementations" section completely reimagined (in general, since both rustdoc and this concept show it in the same way).

The trait section shows so much detail that it misses the forest for the trees. It may display 20 versions of impl<something> Extend<something> for Type<something>, each time with duplicate description of the fn extend, but what it's really trying to say is that the type has an .extend() method that works with several types of parameters.

And there are special traits Ord/Eq/Add/Sub/Mul/Shr which are not important for their own methods, but for what they enable for their type. So maybe they should be handled differently, with a note such as "This type can be compared and used with the following arithmetic operators…".

Similarly with IntoIterator, instead of displaying the trait description, which is more of an implementation detail, it could be replaced with a more concise note along the lines of "This is a container which can be iterated".

6 Likes
#8

It sure could have 20 lines of impl<something> Extend<something> for Type<something> followed by just once the method, if the method didn't have any impl specific docs.

#9

I love to see different approaches. I also like the compact list of methods!

I think that, at the very least, inherent methods and trait methods should be separated. I would prefer if methods were in source order, so that the crate author can design the docs for maximum readability — for a HashMap we expect the basic methods like new, len and get to be near the top.

If the crate author can't determine the order exactly, maybe it would be possible to assign methods to groups and determine the group order?

Having .borrow() as the first method gives it undue attention. This is ultimately confusing for readers, and they will think it's an important method. (The Borrow trait has a blanket impl, so every type will have this method, and I've never used it on a HashMap value!).

6 Likes
#10

I did some changes on the POC according to the feedback.

You are right. I wanted to use a list with icons for consistency, but to display information about generics or enum variants, showing directly the declaration is better. I fixed that.

Yes I did not implemented l&f and responsive design since it's just a POC. They are a lot ok things that can be adjusted. My main concern was not the look but the ways to navigate through the doc.

You are right. Grouping by implementation might me better to have an overview, while grouping by method might be better when you have an idea of what you are looking for. I added a button to switch from a method focused view to an implementation focused view.

I'm not sure a lot of people sort the methods in the source by order of importance for the user. And methods from traits might be as useful as inherent methods(even if it is true that blanket and Auto implementations are often less important).

#12

Given that this is the behavior of the existing rustdoc, and that the standard library provides such nicely ordered methods, I would on the contrary expect that many people are conscientious of this (and those who aren't ought to be!).

(Granted, there is the question of how rustdoc handles inherent impls in other modules. I can only hope they are grouped by module, with those from the struct's own module guaranteed to be first).

I will concede this is true for some crates like rand (and the current form of rustdoc often makes this worse by collapsing these methods from view). I still don't think an alphabetical listing of all methods is superior.

On a related note, I think alphabetical sorting across all traits could actually cause confusion when an inherent method shadows a trait method. See RefCell::borrow, or virtually all inherent methods of frunk::HCons.

1 Like
#13

I had no idea there was a search hotkey in the existing docs, so I think that goes a long way toward showing the better discoverability of an omnipresent search bar.

2 Likes
#14

At least on my comp, it literally says "Click 'S' to search, '?' for more options..." in the search bar.

1 Like
#15

I had to go check and, sure enough, it’s there... in a washed out light grey on white in an area that just looks like text, not a search box.

image
0570346E-1ADD-4043-9026-0852B887A08D.png1334×750 76.1 KB

3 Likes
#16

I can strongly vouch for:

#17

Thank you for sharing this PoC!

I really like the outline the global crate outline, I think it would really help when browsing a crate's documentation.

On the other hand, I'm not a fan of the "alphabetically sorted long list of methods". Or rather, I do think it is useful to have it somewhere, to have the basic information of "what can I call on my type", but maybe not as the first contact with a type. Also I think it could get ugly in certain situations (e.g. a type that implements Iterator and get all of the Iterator methods... to me this would add a lot of noise to the method list).

I don't have a PoC for this, but I would really like rustdoc to be more "capabilities oriented". By this I mean that it should present more "semantic" information about what a user can do with a type. For example:

Construction

  • Contains Self { field : Type, field : Type } if it is available
  • Lists all methods that return Self, Option<Self> or Result<Self>
  • Indicates if the type implements Clone

Conversion

  • Lists all types for which this type implements From (could also go in "Construction" section)
  • Lists all types for which this type implements Into

Iterator

  • If the type is an iterator, indicate the item type.
  • Also special-cased for DoubleEndedIterator and ExactSizeIterator

Future

  • If the type is a future, indicate the item type.

Operations

  • Indicates if the type is Hash
  • Lists all types to which this type is Comparable (Eq, PartialEq or Ord, PartialOrd)
  • Lists all types with which this type has arithmetic operations implemented. For each such type, indicate the available operations.

Formatting

  • Indicates if the type is Debug or Display

Ideally, instead of special-casing everything, traits could add indications to rustdoc in their documentation of how they should appear in the documentation of implementors. This would allow for instance pyo3 PyInto to appear under the "Conversion" section, or serde's Serializable to appear as a small colored tag next to the type name.

8 Likes
#18

The pages don't render well on mobile. It would be better if the side bar hid itself, and the description was moved down to the line below to accommodate the smaller screen size.

#19

Those items sound like great additions. Do you imagine the "Lists all types for ..." to be on the same page and being extended? I mean this could add to the overall size and being more distrustful distractful or do you imagine to have a separate section where i can extend those if i need them?

#20

Well, I'm not a web developer, so I wouldn't know the various technical options we have and their impact on performance in various scenarios (like a type which has a lot of conversions. For the "all the types such..." I was thinking to a list containing just the names of the various types, maybe as colored buttons (pretty much like SO renders tags or this forum renders the categories of a post), but I'm not much of a designer either, so I guess I would have to experiment and see if I can get something good out of the ideas. I'll see if I can find the time someday.

#21

POC : take two

I updated the POC according to the feedback from this thread and my own experience using it.

This time it is not limited to a few handmade pages. The html page of the new poc load the current documentation pages via the fetch API and converted them on the fly to the new format through DOM manipulation. It is a terrible hack, but you can now browse most of the documentation.

A few changes:

  • added a recap of all the implementations
  • moved back the description as first
  • added the ability to group either by implementation(unsorted by default) or by method name(sorted by default)
  • added the ability to sort or not (not sure I will keep it since the default seems fine to me)

What does not work yet but should be fixed :

  • traits pages
  • book pages

What probably won't be fixed because not the target of this POC :

  • Reactive design (View on smartphone)
  • the visuals : icons, fonts, code blocs, ...
  • cross-page links (most are broken but the sidebar should work)
  • back button (broken)

While I like a lot the zkr idea. It raise a lot of questions, so I will consider it maybe in another version of the POC

https://utherii.github.io/new.html

7 Likes