Merge pull request #392 from Ogeon/deny_doc_warnings

Deny documentation warnings in CI

.github/workflows/ci.yml

@@ -95,6 +95,17 @@ jobs:
         run: cargo miri test -p palette --lib --features "bytemuck" -- -Z unstable-options --report-time
       - name: Documentation tests
         run: cargo miri test -p palette --doc --features "bytemuck" -- -Z unstable-options --report-time
+  documentation:
+    name: Documentation
+    runs-on: ubuntu-latest
+    env:
+      RUSTDOCFLAGS: -D warnings
+    steps:
+      - uses: actions/checkout@v3
+      - uses: dtolnay/rust-toolchain@stable
+      - name: "Generate documentation"
+        run: cargo doc -p palette --all-features
+
 
   # Refs: https://github.com/rust-lang/crater/blob/9ab6f9697c901c4a44025cf0a39b73ad5b37d198/.github/workflows/bors.yml#L125-L149
   #
@@ -109,6 +120,7 @@ jobs:
       - check_stable_beta_nightly
       - no_std
       - miri
+      - documentation
     runs-on: ubuntu-latest
     steps:
       - name: Mark the job as a success

.github/workflows/publish_docs.yml

@@ -13,7 +13,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: dtolnay/rust-toolchain@stable
       - name: Generate
-        run: cargo doc --package palette --no-deps
+        run: cargo doc --package palette --no-deps --all-features
       - name: Upload
         uses: JamesIves/[email protected]
         with:

palette/src/alpha.rs

@@ -19,7 +19,7 @@ mod alpha;
 /// channel of a color type. The color type itself doesn't need to store the
 /// transparency value as it can be transformed into or wrapped in a type that
 /// has a representation of transparency. This would typically be done by
-/// wrapping it in an [`Alpha`](crate::Alpha) instance.
+/// wrapping it in an [`Alpha`] instance.
 ///
 /// # Deriving
 /// The trait is trivial enough to be automatically derived. If the color type

palette/src/blend.rs

@@ -13,9 +13,8 @@
 //! let c = a.overlay(b);
 //! ```
 //!
-//! Blending equations can be defined using the
-//! [`Equations`](crate::blend::Equations) type, which is then passed to the
-//! `blend` function, from the `Blend` trait:
+//! Blending equations can be defined using the [`Equations`] type, which is
+//! then passed to the `blend` function, from the `Blend` trait:
 //!
 //! ```
 //! use palette::LinSrgba;

palette/src/cam16.rs

@@ -33,12 +33,12 @@
 //! For more control over the attributes to use when converting from CAM16, one
 //! of the partial CAM16 types can be used:
 //!
-//! * [`Cam16Jch`](crate::cam16::Cam16Jch): lightness and chroma.
-//! * [`Cam16Jmh`](crate::cam16::Cam16Jmh): lightness and colorfulness.
-//! * [`Cam16Jsh`](crate::cam16::Cam16Jsh): lightness and saturation.
-//! * [`Cam16Qch`](crate::cam16::Cam16Qch): brightness and chroma.
-//! * [`Cam16Qmh`](crate::cam16::Cam16Qmh): brightness and colorfulness.
-//! * [`Cam16Qsh`](crate::cam16::Cam16Qsh): brightness and saturation.
+//! * [`Cam16Jch`]: lightness and chroma.
+//! * [`Cam16Jmh`]: lightness and colorfulness.
+//! * [`Cam16Jsh`]: lightness and saturation.
+//! * [`Cam16Qch`]: brightness and chroma.
+//! * [`Cam16Qmh`]: brightness and colorfulness.
+//! * [`Cam16Qsh`]: brightness and saturation.
 //!
 //! Generic traits and functions can make use of the [`IntoCam16Unclamped`],
 //! [`FromCam16Unclamped`], [`Cam16IntoUnclamped`], and [`Cam16FromUnclamped`]

palette/src/color_difference.rs

@@ -255,11 +255,10 @@ where
 /// Euclidean space.
 ///
 /// Euclidean distance is not always a good measurement of visual color
-/// difference, depending on the color space. Some spaces, like
-/// [`Lab`][crate::Lab] and [`Oklab`][crate::Oklab], will give a fairly uniform
-/// result, while other spaces, such as [`Rgb`][crate::rgb::Rgb], will give much
-/// less uniform results. Despite that, it's still appropriate for some
-/// applications.
+/// difference, depending on the color space. Some spaces, like [`Lab`] and
+/// [`Oklab`][crate::Oklab], will give a fairly uniform result, while other
+/// spaces, such as [`Rgb`][crate::rgb::Rgb], will give much less uniform
+/// results. Despite that, it's still appropriate for some applications.
 pub trait EuclideanDistance: Sized {
     /// The type for the distance value.
     type Scalar;

palette/src/lib.rs

@@ -110,9 +110,9 @@
 //! There are many cases where pixel transparency is important, but there are
 //! also many cases where it would just be unused memory space. Palette has
 //! therefore adopted a structure where the transparency component (alpha) is
-//! attachable using the [`Alpha`](crate::Alpha) type. This approach has shown
-//! to be very modular and easy to maintain, compared to having transparent
-//! copies of each type.
+//! attachable using the [`Alpha`] type. This approach has shown to be very
+//! modular and easy to maintain, compared to having transparent copies of each
+//! type.
 //!
 //! An additional benefit is allowing operations to selectively affect the alpha
 //! component:

palette/src/oklch.rs

@@ -20,7 +20,7 @@ mod properties;
 #[cfg(feature = "random")]
 mod random;
 
-/// Oklch, a polar version of [Oklab](crate::Oklab).
+/// Oklch, a polar version of [Oklab].
 ///
 /// It is Oklab’s equivalent of [CIE L\*C\*h°](crate::Lch).
 ///