Relm4: Builds on docs.rs are broken

Open tasks

• A PR for 0.5 (relm4 and relm4-components) https://github.com/Relm4/Relm4/pull/316
• A backport to the stable branch for 0.4 https://github.com/Relm4/Relm4/pull/293
• A new release for 0.4 (I can take care of that)
• The stable docs generated by relm4-docs should show a deprecation warning (I think nightly docs are still kinda nice to have)
• We should move some of the pre-proccessed doc headers into the source code (especially the link collection is pretty useful I think). https://github.com/Relm4/Relm4/pull/338
• Update the links on the website and in the README (and everywhere else, probably some links in the book too)

Why is this important?

Whenever a crate is published on crates.io, its documentation is automatically built and linked. Since you added a documentation attribute to the Cargo.toml files, the default link to docs.rs is replaced by that link. I am sure you had some reasons to do that but I am not a fan of it. I know that all gtk crates do that too, so maybe that was the idea. The downside of this is that the documentation is only available in the current version. If I use an older version, I can’t have a look at its documentation (or it is not obvious how to do that). Luckily it is always possible to just go to docs.rs/crate/CrateName and view the documentation there. On docs.rs it is possible to look at all previous versions. This is why there is value in having working builds on docs.rs.

What is the issue?

Unfortunately the build of the current version is broken. I had a similar problem with one of my crates and I believe the reason is that the dependencies are not available. This should be possible to be fixed by adding something along the lines of

[package.metadata.docs.rs]
features = ["dox"]

[features]
dox = ["gtk/dox", "adw/dox"]

to the Cargo.toml file. The same also applies to relm-components. relm-macros builds fine. It is possible to test the build locally by following this guide: https://github.com/rust-lang/docs.rs/blob/master/README.md#build-subcommand

Explanation of the proposed solution

Here is my understanding of how this fixes the error:

[package.metadata.docs.rs]
features = ["dox"]

This tells docs.rs to activate the feature dox.

[features]
dox = ["gtk/dox", "adw/dox"]

If the feature dox is active, it activates it in the crates gtk4 and libadwaita too. This features allows building the docs without the dependencies.