Show features in documentation

[DerZade]

I license past and future contributions under the dual MIT/Apache-2.0 license,
allowing licensees to choose either at their option.

---

This PR will improve the crate's docs.rs page by showing everything that is exported (even those things which are not included in the default features). Everything that is behind a feature flag will be marked as such.

---

For anyone, who wants to try this out locally:

cargo +nightly rustdoc --all-features --open -- --cfg docsrs

[fintelia]

I think we have to avoid enabling the avif and benchmarks feature or we'll have build issues when docs.rs tries to compile the crate. The one feature we do want to enable however is rayon:

Suggested change

	all-features = true
	features = ["rayon"]

[DerZade]

Just having looked at the code for a tiny bit

I don't think benchmarks should be an issue since everything that depends on benchmark is behind #[cfg(test)] anyway. A quick local rustdocs build confirmed that or am I missing something here?

Why is aviv a problem? Because it depends on the dav1d system lib? Tbh I don't really have experience with docs.rs and system libraries, but I would hope that sys libraries are not an issue for docs.rs, since there are many crates with system lib dependencies on docs.rs, right? That is just me assuming tho 😅, do you have any experience with that?

[fintelia]

I haven't specifically tested, so I'm not 100% sure. But my main concern is around the dav1d crate IIRC needing some combination of ninja-build, meson or nasm at compile time. The docs.rs container image contains some native dependencies but likely not those.

Really we should figure out how to do a test documentation build with an environment matching what docs.rs uses. That would definitively reveal what features do/don't work

[DerZade]

So looks like dav1d does not work with docs.rs (see here), which is kind of a shame. I wish they would just handle the docs.rs environment in their build script, like suggested here. Maybe I'll add a PR for the dav1d-sys crate in the next few days (don't know if I'll get to it tho).

Apart from that, there apparently is a way to add system libraries to the docs.rs build environment as well as a way to test the build in the same environment as docs.rs. I'll see if I can find some time to test it in the next few days, but again, I can't make any promises.

[fintelia]

Thanks for this PR! I think the approach is nicer than in #2063

[DerZade]

Thanks for this PR! I think the approach is nicer than in #2063

Oh I didn't realize that there was already a PR. Tbh I didn't even check 🙈. I stumbled upon this because I wanted to use the WebPEncoded, which is not (entirely) documented atm, since it is not included in the default features. Instead of complaining I just thought I'd copy paste the solution from one of my projects open a PR 😇

[DerZade]

For the record, I just opened a PR for dav1d-rs (rust-av/dav1d-rs#90) to fix their docs.rs build.

[fintelia]

Ok, lets wait for dav1d-rs to release a new version that includes that PR.

I figured out how to test how docs.rs will build a crate:

# Pull the docker container
docker pull ghcr.io/rust-lang/crates-build-env/linux:latest

# Run docker
docker run --name docsrs -it -p 127.0.0.1:8000:8000 ghcr.io/rust-lang/crates-build-env/linux:latest

# Install rust (be sure to select 'nightly')
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Download the crate
git clone ...

# Compile (the 'RUSTDOCFLAGS' and '--all-features' are based on the contents in Cargo.toml)
RUSTDOCFLAGS="--cfg docsrs" cargo rustdoc --all-features

# Launch a webserver to display the docs
cd target/doc/image && python3 -m http.server

[DerZade]

I updated dav1d to the latest version (which works on docs.rs) and added the package.metadata.docs.rs section to the Cargo.toml.

I also tested the docs build with the container as suggested by @fintelia

So I think this PR is ready to be merged :)