Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Show features in documentation #2066

Merged
merged 4 commits into from
Jan 6, 2024
Merged

Show features in documentation #2066

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e58822b
Show features in documentation
DerZade Dec 10, 2023
32bf221
Merge branch 'image-rs:master' into docs-features
DerZade Jan 6, 2024
0964379
build: update dav1d to version 0.10.2
DerZade Jan 6, 2024
8641026
Add package.metadata.docs.rs section to Cargo.toml
DerZade Jan 6, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,10 @@ criterion = "0.5.0"
# feature when testing, so `cargo test` works correctly.
jpeg = { package = "jpeg-decoder", version = "0.3.0", default-features = false, features = ["platform_independent"] }

[package.metadata.docs.rs]
all-features = true
Copy link
Contributor

@fintelia fintelia Dec 11, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"]

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor

@fintelia fintelia Dec 11, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

rustdoc-args = ["--cfg", "docsrs"]

[features]
# TODO: Add "avif" to this list while preparing for 0.24.0
default = ["gif", "jpeg", "ico", "png", "pnm", "tga", "tiff", "webp", "bmp", "hdr", "dxt", "dds", "farbfeld", "jpeg_rayon", "openexr", "qoi"]
Expand Down
1 change: 1 addition & 0 deletions src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,7 @@
#![cfg_attr(all(test, feature = "benchmarks"), feature(test))]
// it's a backwards compatibility break
#![allow(clippy::wrong_self_convention, clippy::enum_variant_names)]
#![cfg_attr(docsrs, feature(doc_auto_cfg))]

#[cfg(all(test, feature = "benchmarks"))]
extern crate test;
Expand Down
Loading