Use crate documentation url

[bilelmoussaoui]

In the case of various crates we have for glib based libraries bindings, the documentations generated with a simple cargo doc don't contain any documentations due to licensing issues. As we can't "overwrite" the source files during the doc stage, because the files are read only, we opted for deploying our docs using CI ourselves.

Sadly, now once we will have a release, people looking for say gtk4 in docs.rs will end up with pretty poor quality docs instead of the one specified in Cargo.toml's documentation url.

I wonder if there's a possibility to make the docs.rs url point to that in such case instead of re-building the docs as part of docs.rs, it could be even something to opt-in for somehow.

See https://docs.rs/gtk/0.9.2/gtk/ for example instead of https://gtk-rs.org/docs/gtk/

[syphar]

@bilelmoussaoui this looks like a duplicate of #125, does it? Or am I missing something?

[bilelmoussaoui]

Ah indeed, my bad I didn't notice it, sorry for the noise. I will copy over my comment to the other issue

Thanks @syphar :)

[jyn514]

I don't think this is a duplicate. It's very reasonable for the link to go to the other url if the build fails. I don't think we should use the link if it succeeds, since not all documentation URLs are actually rustdoc pages.

[jyn514]

@bilelmoussaoui Assuming that gets implemenred, if the build succeeds but with poorer quality docs, you could add a cargo feature which just gives a compile error 😆 and then that fails the build and docs.rs links to the full docs.

[Nemo157]

Alternatively, gtk-rs could reimplement the doc-embedding to use macros instead of modifying immutable source files, a proc-macro based solution would be pretty easy:

#[cfg_attr(include_docs, lgpl_docs::embed(AboutDialog))]
pub struct AboutDialog;

or with 1.54 even a macro_rules! solution is possible

#[cfg_attr(include_docs, doc = lgpl_docs::embed!(AboutDialog))]
pub struct AboutDialog;

[Nemo157]

It's very reasonable for the link to go to the other url if the build fails

The majority of build failures are transient issues in the package. I don't think we would want to default to auto-redirecting to the documentation url on all build failures.