Host API docs on the website (including bleeding-edge docs)

[Nilirad]

In the current state, API documentation is left to be auto-generated and hosted by docs.rs when we cargo publish a new version. This requires no effort, but the results are not excellent, especially for a library with many crates like Bevy. By hosting the docs on our own, we can have better control over the generated output.

Benefits

• cross-crate navigation: This is the main concern. docs.rs generates the docs once for each crate, but it doesn't include dependencies. Thus, if we are in the bevy_app crate and we click a link that bring us to a struct defined in bevy_ecs, we lose some perks, like the src links.
• styling: with cargo doc it's possible to style with CSS the generated docs to give them a unique look.
• main branch docs: API docs for the main branch can be generated. This is of minor concern though since it can easily be generated locally.

Strategy

• Change the various Cargo.toml files to include the URL for documentation
• (optional, but would save a lot of labor) Set up a GitHub action for deployment. When run, this will cargo publish the next Bevy version and run a command like cargo doc --workspace --exclude ci --no-deps, storing the output into a subdomain of the website, like api.bevyengine.org
• change the docs on the website to the new location.

[ickk]

This is a good idea.

I think it makes more sense to serve it under something like docs.bevyengine.org rather than api.

In fact, it might make more sense to host it under just bevyengine.org/docs/api/v0.5. It would:

• integrate better with the existing website,
• not require extra TLS certs/configuration, and
• could be hosted from the same github pages repo as the main website,
• allow other kinds of non-api docs to be hosted in a logical way (i.e. bevyengine.org/docs/book/v0.6)

Agree that a github action is probably the way to go. It could track all tags (0.4, 0.5, main) so users can get the latest docs for any particular release.

Problem: The github pages repo used for the website would probably get pretty noisy.

There's not a lot of good solutions here aside from

• using the subdomain like your original suggestion, or
• splitting each part of the site into a separate repo (index, newsletter, docs) and use some kind of gh action that would combine them (possibly making use of git submodules) into a single automated pages repo.

[Nilirad]

it might make more sense to host it under just bevyengine.org/docs/api/v0.5

Correct, since the header isn't generated like in docs.rs (maybe there is a flag for that?)

splitting each part of the site into a separate repo (index, newsletter, docs) and use some kind of gh action that would combine them (possibly making use of git submodules) into a single automated pages repo.

I prefer this, but I think is better to not fragmentate everything, at least for now, but just store the API docs in a different repo.

[bjorn3]

could be hosted from the same github pages repo as the main website,

Storing the API docs in the bevyengine/bevy repo allows for easier building of the docs on CI.

Agree that a github action is probably the way to go. It could track all tags (0.4, 0.5, main) so users can get the latest docs for any particular release.

Released versions can already be accessed from docs.rs. What is the value in also hosting it ourself?

[Nilirad]

Storing the API docs in the bevyengine/bevy repo allows for easier building of the docs on CI.

That would just mean to .gitignore target except from target/doc. I don't like it very much though: it would pollute the git history with stuff that it's not basically engine development. If I remember well there are things called hooks on GitHub Actions that can be used to trigger a workflow from stuff happened from another repository (like a push to main on bevy).

Released versions can already be accessed from docs.rs. What is the value in also hosting it ourself?

That's the whole point of this issue. I actually noticed the problem while working with @alice-i-cecile on #176. There are many flimsy stuff with multi-crate workspaces in docs.rs, like links to source not being available while browsing from the main crate because docs.rs creates the docs on a per-crate basis instead of the whole workspace.

[bjorn3]

That would just mean to .gitignore target except from target/doc. I don't like it very much though: it would pollute the git history with stuff that it's not basically engine development. If I remember well there are things called hooks on GitHub Actions that can be used to trigger a workflow from stuff happened from another repository (like a push to main on bevy).

My idea was to in a gha workflow push to the gh-pages branch. Checking in target/doc doesn't do anything. Only the gh-pages branch is visible on github actions. As for keeping it in the bevy-engine/bevy repo, that allows force-pushing the gh-pages branch to prevent it from growing forever. In addition I think it is a bit easier to push to a branch on the same repo than to a branch on another repo.

[Nilirad]

Pros/cons of different cargo doc commands

cargo doc -p bevy --no-deps

Pros:

• Docs built only once
• Faster building
• Links work well

Cons:

• No src links
• No crate list available for navigation or search filtering

cargo doc --workspace --exclude ci --no-deps

Pros:

• Crate list available for navigation or search filtering
• Links work from bevy crate
• src links present from bevy crate

Cons:

• Docs built twice (first by bevy, then by every sub-crate)
• Slower building
• Links don't work from sub-crates
• src links missing in sub-crates

I also tried excluding bevy or making #[doc(hidden)] the exported crates by bevy, with disappointing results.

Using rustdoc is so frustrating. I need to do some research in the next days to see if it's possible to call a generation command that:

• Builds doc items only once
• Makes cross-crate links always work
• Always generates links to source
• Has crate list available for search filtering and crate navigation

[Nilirad]

My idea was to in a gha workflow push to the gh-pages branch. Checking in target/doc doesn't do anything. Only the gh-pages branch is visible on github actions. As for keeping it in the bevy-engine/bevy repo, that allows force-pushing the gh-pages branch to prevent it from growing forever. In addition I think it is a bit easier to push to a branch on the same repo than to a branch on another repo.

That could work, at least for main docs. For released versions is a problem though, unless we can make a branch for each version.

[bjorn3]

Builds doc items only once

That is #[doc(no_inline)] or something like that. It would make docs.rs less navigatable. Could be put behind a cfg I guess.

For released versions is a problem though, unless we can make a branch for each version.

Only one branch is possible on github pages. It would be possible to amend every time and only clear the docs for the main branch I think.

[alice-i-cecile]

This is half-done: https://dev-docs.bevyengine.org/bevy/index.html now works :D

[alice-i-cecile]

For the second half of the solution, I would like to host the new-book branch (and future equivalents) on dev-book.bevyengine.org.

@cart is open to the idea, so what would we need to make this happen?

[bytemuck]

I think it's a great idea. Mainly because users love when everything is constant. Putting the docs on the website will make possible to keep the "profile/layout/visuals" that already exists on the main website.

Moreover, the fact that the docs will stay under the same domain as the main website is a bonus.

[alice-i-cecile]

More discussion on one path forward in #313.