Opting Out

[SergioBenitez]

Hello!

I'd like to opt-out from having documentation served on docs.rs for some of my crates. How can I do this?

One idea is that docs.rs would read the documentation link in the Cargo.toml file for a given crate and only serve documentation for the crate if it points to docs.rs. If it doesn't, then visiting docs.rs/{crate} would redirect to the URL in the documentation value.

Another approach is to expand #73 so that package.metadata.docs.rs includes an opt-out key that can be set to true to opt-out.

[onur]

Hi Sergio.

Currently there is no way to opt-out crates from docs.rs. One of the reason I made docs.rs is because there are so many crates with a broken documentation link.

Your second approach is more suitable for me.

If it's not personal I'd like to hear why you're considering to opt-out your crates from docs.rs.

[SergioBenitez]

There a few reasons:

1. Availability. docs.rs has had downtime that I don't consider acceptable. In contrast, documentation that I serve only goes down when a suite of Amazon services goes down, which hasn't happened yet.
2. Enabling of features. I usually want documentation to be served with all features enabled so that documentation for all types and traits is available. This can be solved if Add docs.rs metadata and custom builds #73 is merged.
3. Updating docs without a new version. docs.rs only updates a crate's documentation on new versions, so even the most minor of documentation fixes can impose a version bump if I want documentation to be updated on docs.rs.
4. Inter-documentation linking. When types are reexported, relative links in that type's documentation become inconsistent. To fix this, I use absolute links in my documentation, but these don't work with docs.rs.

There are a few other issues I have, but these are the most important.

[roblabla]

Instead of an opt-out, it'd be nice if docs.rs could have a "canonical docs" link shown prominently somewhere in the case the documentation link is different from docs.rs.

However, I really wish docs.rs does not allow "opting out". I have seen so many crates out there with broken docs, or docs that didn't have the features of docs.rs such as building the docs for different platforms. If people start opting out of docs.rs, I feel this service will become less relevant.

[Arnavion]

I suppose one can add a __docs_rs_build feature that's only enabled for docs.rs via package.metadata.docs.rs.features, and use it for the crate docs attr:

#![cfg_attr(feature = "__docs_rs_build", doc = "This crate's docs are not hosted on docs.rs. [Click here](https://self/hosted/docs/) to visit the docs.")]
#![cfg_attr(not(feature = "__docs_rs_build"), doc = "<real docs>")]

You'd also have to put the #[cfg_attr(not(feature = "__docs_rs_build"))] on every item and module in the crate root.

[jyn514]

Enabling of features. I usually want documentation to be served with all features enabled so that documentation for all types and traits is available. This can be solved if #73 is merged.

#73 has been merged.

Inter-documentation linking. When types are reexported, relative links in that type's documentation become inconsistent. To fix this, I use absolute links in my documentation, but these don't work with docs.rs.

This should be possible to do without absolute links if you use intra-doc links.

Availability. docs.rs has had downtime that I don't consider acceptable. In contrast, documentation that I serve only goes down when a suite of Amazon services goes down, which hasn't happened yet.
Updating docs without a new version. docs.rs only updates a crate's documentation on new versions, so even the most minor of documentation fixes can impose a version bump if I want documentation to be updated on docs.rs.

Yeah, that's reasonable. I'm curious though why you want to opt-out altogether rather than just adding a big "go to https://rocket.rs/" at the top of your crate-level docs if they're built by docs.rs.

[Arnavion]

I'm curious though why you want to opt-out altogether rather than just adding a big "go to https://rocket.rs/" at the top of your crate-level docs if they're built by docs.rs.

It doesn't help when docs.rs failed to build your crate's docs, either because it needs a dep that isn't available, or more likely because it broke again and won't be fixed for two months.

[Nemo157]

If the docs don't build, then docs.rs redirects to its crate details page, which includes a link to the package.documentation url and the rendered readme.

[Arnavion]

From https://docs.rs/crate/ruspiro-interrupt/0.4.3 (which I picked from https://docs.rs/releases/recent-failures ), the things that catch the eye are the colored box talking about the build failure, followed by a link to the docs for an older crate version. I don't think it can be reliably expected that the README below it will be read.

I assume "a link to the package.documentation url` is the "Documentation" item in the left sidebar, which is even less noticeable.

[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/

Copied from my duplicate issue at #1406

[kinnison]

In addition, if a crate exists purely to support a bunch of binaries which are the real product (e.g. subplot) then it'd be nice to exclude that crate's docs, though I suppose I could #[doc(hidden)] all the stuff and put a "This is for internal use only" all over the place. Seems a waste of docs.rs CPU/Storage at that point though.