bevyengine / bevyengine/bevy-website

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

Open
#181 12 comments 0 reactions 0 assignees View on GitHub
A-Build-System
Dominant language
JavaScript
Stars
249
Forks
450
Avg merge
16h 20m
Merged PRs (30d)
6

Description

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](https://doc.rust-lang.org/rustdoc/what-to-include.html#customizing-the-output) 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.

Contributor guide

Open the contributing guide

Research direction

Review the various Cargo.toml files and the website documentation references, then inspect the existing release workflow before evaluating the proposed cargo doc --workspace --exclude ci --no-deps command. Define whether deployment is part of the work and verify that published API docs, main-branch docs, cross-crate navigation, and the website links all point to the intended location.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, rust
Domain
ci-cd, documentation, release
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
28/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.