bevyengine / bevyengine/bevy-website
Host API docs on the website (including bleeding-edge docs)
- 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
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