Add dead-link checking to CI

[alice-i-cecile]

This also needs to work for broken short-codes, which are particularly easy to screw up / hard to verify and will break whenever we refactor a referenced item with a rename / module move.

[cart]

Agreed. To properly capture short code (and other template) dead links, this should run on the "zola outputs" and not the "zola inputs".

[alice-i-cecile]

In order for this to be ergonomic when writing new docs content, we need a way to verify these links against the current main branch Bevy API. E.g. I'm attempting to link to App::add_system, but on 0.5 (latest) it's still under AppBuilder. We need to be able to write and verify docs before releases.

bevyengine/bevy#1731 is probably necessary for this to work.

[alice-i-cecile]

@mockersf noted that one of the largest difficulties in fully solving this will be verifying that method / field calls are valid. Missing types etc return a 404, but that's not the case if the anchor (i.e. #method.get) is wrong. We may need to tweak an existing dead link checking script to work specifically with the Rust doc sites information in a smarter way.

That said, even basic 404 checking would help improve quality significantly.

[cart]

In order for this to be ergonomic when writing new docs content, we need a way to verify these links against the current main branch Bevy API. E.g. I'm attempting to link to App::add_system, but on 0.5 (latest) it's still under AppBuilder. We need to be able to write and verify docs before releases.

Yup good points. I think we can find a way to make the version "globally configurable" for short codes. Either by just manually modifying the shortcode impl or by using some sort of "global version config".

@mockersf noted that one of the largest difficulties in fully solving this will be verifying that method / field calls are valid. Missing types etc return a 404, but that's not the case if the anchor (i.e. #method.get) is wrong. We may need to tweak an existing dead link checking script to work specifically with the Rust doc sites information in a smarter way.

Arg I wasn't aware of that. I agree that we should ultimately add some custom logic here. I also agree that basic 404 checking is a good start.

I also want to eventually adopt our own "rust based dead link validator task" if possible. I don't like that users cant easily do dead link checks on their machines. In the same way that they can do clippy and fmt validations.

[alice-i-cecile]

Duplicate of #177.