TLDR: writing good lib docs are tricky, especially with the current doc tools. I try to provide a little overview of the current situation and present a mockup of what the main page might look like if rustdoc was expanded to include better structure presentation
According to this other thread, documenting libs well is problematic. For one, the libs docs just tend to be a compilation of what makes the library convenient to use but this is problematic to explain. For one, the docs don’t provide any structure outside of the inherent structure of the library (without delegating to say dummy modules for the purpose of exposition).
Even a decently documented lib such as regex has quite a detailed front page with a lot of detail but it is not easily consumed without just skimming the entire document. Another similar example would be std::collections. In contrast, serde does not have an extensive front page and so users are left to just browse at random trying to figure the library out on their own.
Furthermore, a library like regex might benefit from having separate categories for things like character class documentation and grouping annotation as opposed to matching examples and introduction text. Even if the library authors wanted to separate out these documents into separate docs, they’d be less likely to setup 3 different sites for doc hosting on top of setting up working doc systems that suits their needs. Rustdoc handling all these aspects would certainly be ideal.
As is, the left sidebar really isn’t that helpful but I didn’t discard it (it’d probably/possibly still be inside “libs”). The main idea is have section categories in the sidebar which stay with you as you read (like mozilla does with right sidebar here). You should always be able to see the categories but the TOC could possibly scroll I suppose. I also tried a mockup with tabs at the top but I don’t like giving up vertical space to a floating top bar.
Here’s the mockup:
I’m aware this would probably require some rustdoc convention of having a “doc” folder or module for structure which wouldn’t be well specified yet. I imagine it would also require some experimentation and testing to see how much, the regex crate for example, would benefit from something like this. Either way, I thought having a mockup might be helpful at least to have a concept of what it might look like.
Also, I have this picture as an
*.svg from inkscape. I can upload if someone else wants to play with it.