Support multi-crate projects

[dhardy]

Summary

Suggestion: host multiple crate's docs under the same "site", e.g. https://docs.rs/rand/

Motivation

Generated docs (at least sometimes) include a list of "Crates" in the sidebar. This can be seen, for example, on the Rand project's self-hosted docs, as well as on any locally built docs.

Example: https://rust-random.github.io/rand/rand/

This would also partially solve #204.

Details

Support building and serving docs for multiple (selected) crates from the same "site". For example:

• https://docs.rs/rand/latest/rand/trait.Rng.html
• https://docs.rs/rand/latest/rand_core/trait.RngCore.html
• https://docs.rs/rand/latest/rand_chacha/type.ChaChaRng.html

Crates served from a different site would redirect, e.g. https://docs.rs/rand_core/latest/rand_core/trait.RngCore.html redirects to https://docs.rs/rand/latest/rand_core/trait.RngCore.html .

How to select when to serve a crate from a different site is worth considering; I can see two possibilities:

• Automatically based on the repository (e.g. rand, rand_core and rand_chacha are all in the same repo)

• Manually via Cargo.toml, e.g.

  [package.metadata.docs.rs]
  all-features = true
  site = "rand"
  

Issues

Versions are crate-specific. Even when projects release multiple crates simultaneously under the same number, this cannot be guaranteed. Hence a URL like this makes no sense:

• https://docs.rs/rand/0.8.5/rand_core/trait.Rng.html

0.8.5 is a rand version; there is no rand_core v0.8.5 (yet)!

How to solve this isn't obvious and it may kill this suggestion. Moving the version number after the crate name (docs.rs/rand/rand_core/0.6.4/trait.Rng.html) would break with current docs.rs behaviour and break relative to locally-functional links (as used in https://rust-random.github.io/rand/rand/).

A possibility: replace the version in the URL with a date. Regenerate the whole "site" whenever any crate is updated (maybe after a delay to accommodate multiple simultaneous publications). Keep the crate version in the top-bar based on the currently viewed crate.

[Nemo157]

I definitely think it would be nice if we could do something like this.

Both the suggestions on how to decide what to include in a site seem easy to game, anyone can set the package.repository or package.metadata.docs.rs.site of their crate to get it included in someone else's site. Potentially leveraging package namespaces (RFC 3243) if that is accepted would be a good approach, though I could see situations where crates are not in a shared namespace and still want their docs bundled together, also I have some crates that I would likely put in a namespace but I don't want some of them bundled because they are internal implementation details.

One idea might be to make it fully explicit from the top-level crate defining the site

# rand/Cargo.toml
[package.metadata.docs.rs.site-dependencies]
rand-core = { version = "0.6.4" }
rand-chacha = { version = "0.3.1" }

That way it's fully under its control which other crates are built and bundled into its sidebar. It would also help with versioning, the versions selected and built during each release are what are available with it. If there is a new version of rand-core released and you want that bundled in with rand you would have to release a new version of rand with that bumped dependency.

That wouldn't allow for redirecting from the bundled crates docs to the site though, since now anyone could bundle your crate docs into their site. So maybe it'd need notation on both sides (though that might become complex to track exactly which redirect target should be used for versioned urls).

[dhardy]

A possible work-around is not to redirect: each crate gets its own docs.rs site, but some include others (as above).

Question: does the site get updated when a dependency gets a new patch version? Ideally yes, but...

... how do perma-links work when the version belongs to the site crate, but a site-dependency gets a new patch version? One could encourage people to use links to the crate's own docs for this, but it's a poor solution.

So, possibly, the above works but without updating for new site-dependency versions.

Another minor detail: a site-dependency might not be a crate dependency. It might even be a dependant, and published afterwards, therefore the mentioned version may not exist yet on crates.io when docs.rs attempts to generate docs.

[syphar]

I'm closing this issue in favor of #2457 (the tracking issue for packages as optional namespaces.