Relm4 Builds on docs.rs are broken

Open tasks

[x] A PR for 0.5 (relm4 and relm4-components) https://github.com/Relm4/Relm4/pull/316
[x] A backport to the stable branch for 0.4 https://github.com/Relm4/Relm4/pull/293
[x] ~~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)
[x] 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.

Oct 03 '22 21:10 pentamassiv

I love the new 0.5 version by the way. Feels so much easier :+1: :1st_place_medal:

Oct 03 '22 21:10 pentamassiv

I would be very happy to have this resolved and the custom build jobs removed. Honestly, maintain the build jobs has been quite a bit of work.

A PR that addresses this should consider adding more doc examples to compensate the loss of the scrape examples feature.

Oct 03 '22 21:10 AaronErhardt

I did not know about the scrape examples feature before. Very interesting. On the page you linked, it says: To enable this feature on docs.rs, add this to your Cargo.toml:

[package.metadata.docs.rs]
cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples=examples"]

It looks like you could just add that and then there would be no need to make other changes to the documentation.

Oct 03 '22 21:10 pentamassiv

Nice, I've overlooked that. In this case, we need the following steps

[ ] A PR for 0.5 (relm4 and relm4-components)
[ ] A backport to the stable branch for 0.4
[ ] 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).
[ ] Update the links on the website and in the README (and everywhere else, probably some links in the book too)

Oct 03 '22 21:10 AaronErhardt

Okay, I can work on that. I'll start with the backport since that is the easiest way to see if it actually fixes the builds

Oct 03 '22 22:10 pentamassiv

Regarding the nightly docs, my suggestion would be to get rid of them too and publish prerelease versions of the crates instead. They will be ignored when running cargo update, but the docs will be built on docs.rs and the version will be visible when clicking on "versions" on crates.io. When searching for a crate, only the most recent stable version will be displayed, so there should not be any danger of users accidentally using unstable versions. An example for a crate that does this is https://crates.io/crates/wayland-server. The way prerelease versions are published seems to be to add something like -beta.2 to the version field in Cargo.toml and running cargo publish (source). Since you already append these strings to beta versions, all you'd need to do is publish them.

Benefits

you can completely get rid of your custom build jobs
users can use crates.io for unstable versions if they opt-in
users can freely switch between unstable and stable versions

Oct 03 '22 23:10 pentamassiv

I'm aware of that. But we can't publish with git dependencies and AFAIK still need those for the glib crate.

In the past, gtk-rs and libadwaita-rs weren't very eager with publishing beta versions on crates.io...

Oct 04 '22 08:10 AaronErhardt

Ah, that's unfortunately true.

Oct 04 '22 13:10 pentamassiv

Feel free to ping me once a new version is released, then I'll do the changes for 0.5

Oct 04 '22 14:10 pentamassiv

I think the new version you published will not build. I believe there are some errors with the doc when the tokio-rt feature is active. :( Sorry about that

Oct 04 '22 14:10 pentamassiv

Mhh, that's not good but also not that bad either. We can fix it and follow it up by another version.

Oct 04 '22 14:10 AaronErhardt

Actually, the problem is rather libadwaita: https://docs.rs/crate/relm4/0.4.5/builds/642037

Oct 04 '22 15:10 AaronErhardt

You probably noticed already, but apparently libadwaita doesn't pass the "dox" feature flag to its dependencies, not even the sys crate which causes the actual problem. The build script that causes the error would work otherwise.

Oct 04 '22 17:10 AaronErhardt

Yes, I created a Gitlab account and will create a PR today. After that is accepted, I can do the same thing for libpanel and then we should be good. It might be the case that we can only do this for the 0.5 version though. Not sure if they will publish a new patch version for previous minor versions. This here remains an issue though: https://github.com/Relm4/Relm4/pull/298

Oct 04 '22 18:10 pentamassiv

Here is the MR for libadwaita: https://gitlab.gnome.org/World/Rust/libadwaita-rs/-/merge_requests/50 (Merged)

Oct 04 '22 19:10 pentamassiv

I opened two more PRs to get it working: https://github.com/gtk-rs/gtk-rs-core/pull/778 https://github.com/gtk-rs/gtk4-rs/pull/1135 Once those are merged, I'll do it for libpanel too and then we should be good to go

Oct 06 '22 13:10 pentamassiv

I wonder if it makes sense to back port the changes to Relm4 0.4. This would require a back port for gir, gtk-rs-core, gtk4-rs, libadwaita-rs and libpanel-rs. And quite a few new releases as well of course. It is certainly possible, but I wonder if it's worth the effort. What do you think @pentamassiv ?

Oct 08 '22 08:10 AaronErhardt

Agreed, it's unlikely to happen. I think we would also get a problem with semantic versioning. People using the --all-features config would have their builds fails since all of the sudden, the libraries would not be linked.

Oct 08 '22 09:10 pentamassiv

Is there any progress on this issue? Do you need help with implementing the necessary changes in gir? It would be great to merge this soon so all gtk-rs crates pick up the changes in time for their next release.

Oct 14 '22 20:10 AaronErhardt

Yes, there is some progress on it. My draft was reviewed today and changes were suggested. It is not ready to be merged yet, but I am positive it can cross the finishing line soon https://github.com/gtk-rs/gir/pull/1382

Oct 14 '22 21:10 pentamassiv

Awesome :+1:

Oct 14 '22 21:10 AaronErhardt

Gir now automatically activates the dox feature in sys crates for the dependencies where it is available. gtk-rs-core, gtk3 and gtk4 were also fixed. Libadwaita was fixed a few days ago. The only remaining upstream crate that is missing seems to be libpanel. I create an issue for it: https://gitlab.gnome.org/World/Rust/libpanel-rs/-/issues/3 Next step I guess would be to fix it for relm4 0.5.

Oct 18 '22 22:10 pentamassiv

Apparently libpanel will be fixed in the 1.0.0 release.

Oct 25 '22 22:10 pentamassiv

Yes I think it's already on crates.io, however due to an oversight while re-enabling libpanel, 0.5.0-beta.4 still failed on docs.rs. So I'd like to release beta.5 or even rc1 soon.

Oct 26 '22 07:10 AaronErhardt

Btw. builds on docs.rs look great, so we can now move on with the remaining steps to complete the transition :)

Dec 09 '22 08:12 AaronErhardt

Okay, great. I will have a look at it the next days :)

Dec 10 '22 02:12 pentamassiv

I read through the issue again and I there seems to be very little left to do. Here is what I would suggest:

[x] Change the documentation field in the Cargo.toml files to the docs.rs link (https://github.com/Relm4/Relm4/pull/383)
[x] Change the link on the website to point to docs.rs too but keep the old documentation at https://relm4.org/docs/stable/relm4/ (https://github.com/Relm4/website/pull/5)
[ ] Change the links in the book (https://github.com/Relm4/book/pull/35)
[ ] Wait two months or so to give people time to move the 0.5 release
[ ] Remove the old documentation

Jan 08 '23 17:01 pentamassiv

@AaronErhardt , I remember you changed your mind about keeping the "next" docs but I think your wrote that is some other thread that I can't find anymore. Do you want to keep the next docs or get rid of them?

Jan 08 '23 20:01 pentamassiv

As soon as we release 0.5 as stable we should discontinue the docs and redirect to docs.rs. But we might consider reviving the custom docs builds for "nightly" docs to keep the main branch documented between releases but everything else should be on docs.rs.

Jan 09 '23 16:01 AaronErhardt

I think we're mostly done with this, right? I think we could even disable the Relm4/docs repo since the 0.4 docs are still available.

Mar 13 '23 21:03 AaronErhardt