Test that docs.rs can build our crates

[Michael-F-Bryan]

Motivation

We found that docs for the wasmer 3.2.0 crate weren't able to build in docs.rs because of some bugs around conditional compliation. The underlying issue was fixed in #3791, but it'd be nice to make sure CI warns us when this happens.

Proposed solution

We can use the docs.rs CLI to build things locally (instructions).

In theory, it's "just" a case of running the following:

$ cargo install --git 
$ for $crate in $workspace; do docs-rs  build crate --local /path/to/$crate; done

(this should be automatable using the cargo-metadata crate and a cargo xtask helper)

Alternatives

We can always leave things as they were done in #3791 and make sure we keep that Makefile command in sync with our [package.metadata.docs.rs] metadata.

[syrusakbary]

/bounty $100

[algora-pbc]

💎 $100.00 bounty created by syrusakbary
🙋‍♂️ If you'd like to solve this issue, comment below to get assigned
👉 To claim this bounty, submit a pull request that includes the text /claim #3802 somewhere in its body
📝 Before proceeding, please make sure you can receive payouts in your country
💵 Payment arrives in your account 2-5 days after the bounty is rewarded
💯 You keep 100% of the bounty award
🙏 Thank you for contributing to wasmerio/wasmer!

[meskill]

Can I work on this?

[syrusakbary]

@meskill of course!

[meskill]

I've tried to build and run the docs.rs cli but as mentioned here it actually requires the running database and ability to run container. That all sounds a bit like overkill for just the testing purpose.

My suggestion is to automate process of building the right set of features for building doc by implementing bash script that reads Cargo.toml content and if there are docs.rs related features it will build the doc with these features passed. The implemented script is in #3819

[algora-pbc]

💡 meskill submitted a pull request that claims the bounty. You can visit your org dashboard to reward.

[Michael-F-Bryan]

My suggestion is to automate process of building the right set of features for building doc by implementing bash script that reads Cargo.toml content and if there are docs.rs related features it will build the doc with these features passed.

@meskill I don't think #3819 completely solves the problem. That PR only tested packages with [package.metadata.docs.rs] annotations, so CI says things are fine when the docs for crates like wasmer-cache are broken (#3826).

Can you tweak the script to build docs for all crates in the repository, and use the docs.rs metadata to figure out how the --features flag should be modified.

[ptitSeb]

I'll handle this. I want the docs to be publichsed for the 3.3

[meskill]

Oh, well, I expected some other job in pipelines would show the errors in that case, but seems like they are built with different set of features.

Ok, let me try to improve the script. But, looking at the build log output, I can see a lot of errors that I'm not sure I can fix quickly in order to pass the new test pipeline.

[algora-pbc]

🎉🎈 @meskill has been awarded $100.00! 🎈🎊

[meskill]

I see that @ptitSeb has already changed the script to run on all packages. I've also changed the script accordingly. My version might be used as a reference in case you face problems with figuring out workspace members right.