Rustdoc mockup for including more structured content

tools and infrastructure
3

By the way, I'm not exactly proposing this be done. I was actually just trying to explore to see if a reasonable interface could be found which would make it work without being horrible. I couldn't find any libs which actually try to combine lib docs with usage docs so it's the wild west I guess.

If the interface was decent, then it could be decided whether the result was actually worth it.

Well, suppose having docs span multiple pages was a good idea (I'm not sure if it is or not but for the time being, let's assume it is; this would probably be more important if examples started getting bundled with the libs). Then, rather than having an epic lib.rs file which has some scheme for enabling one file to be separated into a tree structure, you could have say, this:

$ cd my_lib && tree .
.
├── Cargo.toml
└── src
    ├── a.rs
    ├── b.rs
    ├── c.rs
    ├── doc
    │   ├── examples
    │   │   ├── a.rs
    │   │   ├── b.rs
    │   │   ├── c.rs
    │   │   └── mod.rs
    │   ├── mod.rs
    │   └── ref
    │       ├── a.rs
    │       ├── b.rs
    │       ├── c.rs
    │       └── mod.rs
    ├── lib.rs
    └── main.rs

4 directories, 15 files

Maybe it would generate the aforementioned picture where the intro was generated from the readme. Maybe the doc files would be *.md instead. Anyway, this would allow more complicated doc structure shoehorned into the regular format of the libs. The lib structure would be normal. The rest would follow the structure from the doc folder constituents.

Also, this isn't to say an epic lib.rs couldn't be used. But you could choose not to use it if you desired.

Supposed multi-page docs are bad. Then getting a TOC out of the libs could probably be generated in a straightforward fashion from the libs themselves as you suggest. This would probably be a good idea regardless.

Regarding libs, perhaps some things could be done to make them more approachable to newcomers. For example, in the regex crate, of the listed types on the front page, almost every single type is only used indirectly (only 3 out of 14 are useable directly). Constantly finding things you can't use directly makes browsing really difficult (maybe indirect types should only be shown by default in return signatures?).