[Merged by Bors] - Adds docs deadlinks check on CI

[mnmaita]

Closes #1579

This is my first contribution to this repository, feel free to correct anything that I'm missing and I'll address feedback as soon as possible!

[CleanCut]

Since you're running the CI job on Linux, you'll need to add a step to install the Linux build dependencies. 😄

bevy/.github/workflows/ci.yml

Lines 32 to 33 in f61e44d

	- name: Install alsa and udev
	run: sudo apt-get update; sudo apt-get install --no-install-recommends libasound2-dev libudev-dev

[mnmaita]

Since you're running the CI job on Linux, you'll need to add a step to install the Linux build dependencies. 😄

bevy/.github/workflows/ci.yml

Lines 32 to 33 in f61e44d

	- name: Install alsa and udev
	run: sudo apt-get update; sudo apt-get install --no-install-recommends libasound2-dev libudev-dev

Thanks! I just figured that out. 😅

Will be fixing it in a few. ;)

BTW, should I use ubuntu-latest for this job or is it easier to run it on other platform? Any preferences on that?

[CleanCut]

BTW, should I use ubuntu-latest for this job or is it easier to run it on other platform? Any preferences on that?

ubuntu-latest is probably fine. We've generally leaned that way since it has been fastest (or near fastest) while also having very predictable behavior.

[CleanCut]

The dead links have to be fixed as well! Otherwise this PR won't pass CI. 😆

[mockersf]

I... think there are too many dead links to ask it as part of this PR. Around 7000?

We could:

• make it ignore failures for now, as a mean to track
• or open a tracking issue with the dead links split in logical groups to share the effort

[CleanCut]

I... think there are too many dead links to ask it as part of this PR. Around 7500?

That number is high enough to make me suspicious that it's not functioning as intended.

[mockersf]

I checked a few, it seems they all come from methods from the crate downcast-rs

[mnmaita]

I changed this so the deadlinks check doesn't fail, is this acceptable?

I'm not 100% sure on how these are fixed to be honest, any tips?

[CleanCut]

I checked a few, it seems they all come from methods from the crate downcast-rs

Hmm...links from documentation of dependencies of Bevy is probably not helpful.

[mockersf]

ok, after digging more :

• errors from downcast-rs can be "fixed" by running cargo doc --all-features && cargo deadlinks --dir target/doc/bevy instead of cargo deadlinks
• errors from tracing should be fixed on their next release (0.2 with some breaking changes)
• an issue in rustdoc that added an anchor to a section that didn't exist (when implementing Deref for a target that didn't have methods, probably fixed by rust-lang/rust@61c8aae, should be ok in next stable)
• some issues with rust doc itself

so... I think this is not worth it right now, maybe take a look after tracing release 0.2

[cart]

Thanks for looking into it! (I agree)

[mockersf]

fixed a few dead links from rust std: rust-lang/rust#82950, that will be available in two versions so... 2021/05/06

[MinerSebas]

What happens if you --no-deps to cargo doc command?
I suspect it will supress the dependencies errors, but the question is whether it bevy documention will now show errors, due to missing them.

[CleanCut]

@MinerSebas makes a good point that there's no need to check dependencies' documentation links. 👍🏼

[mnmaita]

What happens if you --no-deps to cargo doc command?
I suspect it will supress the dependencies errors, but the question is whether it bevy documention will now show errors, due to missing them.

So should I add --no-deps or replace --all-features?. I did some changes here based on a suggestion, please check that too since I'm kinda playing by ear here 😅.

BTW, I've read that cargo-deadlinks "runs cargo doc for you" so I'm wondering if there's a way to pass down args to that...

[mockersf]

I'm wondering if there's a way to pass down args to that...

Yup, you run cargo doc yourself, with the args you want, then cargo deadlinks --dir path/to/the/doc/you/built

[CleanCut]

To answer your first question: Add --no-deps to your cargo doc you run separately.

[mnmaita]

To answer your first question: Add --no-deps to your cargo doc you run separately.

It's done. I've also updated the branch.

[CleanCut]

Looks great, thanks!

[cart]

Looks good to me. Lets merge this! Anyone want to volunteer to create a tracking issue / lead the effort for resolving deadlinks so we can make this job fail on deadlink detection?

[cart]

bors r+

[mockersf]

#1983 for tracking known dead link sources

[bors]

Pull request successfully merged into main.

Build succeeded:

• build-android
• build (nightly, ubuntu-latest)
• build (stable, macos-latest)
• build (stable, ubuntu-latest)
• build (stable, windows-latest)
• build-wasm (nightly, ubuntu-latest)
• build-wasm (stable, ubuntu-latest)
• markdownlint
• run-examples