Host custom built released docs for Bevy

[mockersf]

Docs built on docs.rs have a few issues for Bevy:

• missing src links
• subject to build queue
• impossible to customise
  • left menu showing components / resources / ... first instead of modules / structs

By building docs ourselves, we could build as a workspace, fixing the src issue, and customise the presentation however we want.

As a nice community feature, we could also build docs for crates present in bevy_assets that depends on the latest version of Bevy and use the same customisation for them.

[james7132]

I'm a bit concerned about what's necessary to achieve this. Is rustdoc extendable enough to support these alterations? If not, how hard would it be to create our own output given the JSON output from rustdoc?

[mockersf]

Looks possible from a first look. Worst case would be adding a link to https://docs.rs/bevy/latest/bevy/ecs/component/trait.Component.html#implementors

[cart]

Those are big wins and I think this is probably justified. My biggest concern is about "competing with docs.rs results on search engines". Seems like we'd be stuck in a dual mode forever.

[mockersf]

A bad solution could be to make docs.rs builds fail...

[stephenmartindale]

I don't think that having no docs on docs.rs is a good idea. Community content and blogs and tutorials and stuff need somewhere to perma.-link to that will have even ancient versions available.

What about:

1. On docs.rs: put a headline at the top of every page hinting that latest docs and those for main are available elsewhere.
2. Custom build the docs for self hosting but put them behind a proxy – nginx or traefik, perhaps – that serves a permanent redirect to docs.rs for version numbers that aren't latest or main

This would reduce the SEO cost. It would still have an impact because it would be the SEO equivalent of "splitting the vote" but both sources for documentation would at least be discoverable.

[cart]

We'd also want to make sure we can support all Bevy releases / make them select-able like they are on docs.rs.

[mockersf]

Do we want to have all versions? Or rely on docs.rs for older versions?

[stephenmartindale]

If it would enable a nicer experience for devs working against main or the latest numbered release, I would certainly vote for self-hosting those, only, and letting docs.rs serve older versions – even if those older docs were flawed.

When all is said and done, developers who do need historical docs for whatever reason can always clone their target and build them, themselves, to read offline – anyone can run cargo doc. They would have to do so if they were using an odd branch or fork, anyway.

[stephenmartindale]

Another issue re. docs.rs is the impossibility of "nice" intra-Bevy but inter-crate linking – see my thread on Discord.

Bevy – concretely, bevy_internal – follows a crate of crates structure but this means that leaf-crates struggle to use rustdoc's link-shorthand to refer to things in crates nearer the root of the tree. For example, try linking to DefaultPlugins – one of the few types actually defined directly in bevy_internal, itself.

The consequence is that the more general a code artefact is, the harder it is to refer to.

If THIS could somehow be fixed, too, that would be grand!