godot-rust / godot-rust.github.io

Website and API Docs infrastructure

Website and API Docs infrastructure

Contains the source files for https://godot-rust.github.io and the CI infrastructure to generate real-time documentation from latest commits. This CI is based on GitHub Actions and offers the following workflow:

• Supports gdnative and gdext repos.
• Triggered via push to master and pull requests.
• Runs cargo doc for the respective branch.
• Creates an overview page with all active docs.
• Deploys generated docs to the website.

The website is built with Zola, a static site generator implemented in Rust. We use a custom theme inspired by Blow, together with Tailwind CSS for styling.

godot-rust.github.io's Issues

Mobile rendering

The scaling and proportions are not great on mobile devices. While I'm not sure how many users truly read the website from their phones, it would still be nice to address this. Probably mostly a matter of adjusting some CSS classes.

Docs generation cannot include 4.x in-dev symbols

Currently, the docs generation uses gdext master branch without custom-godot, so cutting-edge 4.x features (from the in-dev version) are not available to cargo +nightly doc. This noticeably limits visibility of newer features.

For example, after 4.2 is stable, anything with #[cfg(since_api = "4.3")] will only be documented once 4.3 is released.

Unfortunately, we cannot just pretend we are on 4.x, because cargo doc, for some reason, insists that function implementations be correct, not just signatures. They may point to non-existing symbols, since gdext compiles with the C and JSON files generated for last stable Godot.

There are some possible solutions:

1. Enable custom-godot and download nightly Godot builds, just like CI on gdext itself.
   • This would however increase time to build docs; maybe less dramatic with caching.
   • It would also mean that upstream Godot breakage will grind doc generation to a halt. Which can be argued doesn't matter much because our CI is already down anyway.
2. Maintain a godot4-prebuilt branch nightly, which contains the artifacts for Godot nightly builds.
   • Re-generated periodically each night.
   • Instead of custom-godot + downloading engine, we could simply use the [patch] trick to point to that branch.
   • Documentation generation jobs would be fast, however there's some initial effort needed to set up artifacts for nightly builds. It would likely not be useful for the main repo, as those need symbols to work (be backed by nightly engine), not just be available in code.
3. Replace function bodies with todo!() or similar. This is so insane I don't even want to get started. Also since unknown symbols may very well appear outside functions.

rss/atom feed

I was looking for an rss/atom feed for https://godot-rust.github.io/dev/ but could not find one. Is there one?

Faster deployment to GitHub pages

Instead of using the gh-pages branch and going through all the deployment steps with Jekyll, we could use GitHub Actions as announced last year. This would not only be faster, but likely give us more control (e.g. comment on PRs only once the deployment has finished).