Match CI doc testing with docs.rs. (#40)

* Remove `-Zunstable-options -Zrustdoc-scrape-examples` from CI. It
wasn't even enabled for docs.rs and we don't have any examples as
defined by Cargo, so not worth enabling scraping at this point.
* Treat doc warnings as errors. Historically we've not done so due to
various `rustdoc` bugs giving false positives but I got it to pass
without failure right now, so perhaps better times have arrived.
* Enable the `doc_auto_cfg` feature for docs.rs which will show a little
tip next to feature gated functionality informing of the crate feature
flag.
* Pass `--all-features` at docs.rs to match our CI and reduce the
maintenance burden of manually syncing the features list.
* Target only `x86_64-unknown-linux-gnu` on docs.rs as we don't have any
platform specific docs.

.github/workflows/ci.yml

@@ -308,13 +308,15 @@ jobs:
 
       # We test documentation using nightly to match docs.rs. This prevents potential breakages
       - name: cargo doc
-        run: cargo doc --workspace --locked --all-features --no-deps --document-private-items -Zunstable-options -Zrustdoc-scrape-examples
+        run: cargo doc --workspace --locked --all-features --no-deps --document-private-items
+        env:
+          RUSTDOCFLAGS: '--cfg docsrs -D warnings'
 
-  # If this fails, consider changing your text or adding something to .typos.toml
+  # If this fails, consider changing your text or adding something to .typos.toml.
   typos:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
       - name: check typos
-        uses: crate-ci/typos@v1.26.0
+        uses: crate-ci/typos@v1.27.0

Cargo.toml

@@ -30,6 +30,12 @@ license.workspace = true
 edition.workspace = true
 repository.workspace = true
 
+[package.metadata.docs.rs]
+all-features = true
+# There are no platform specific docs.
+default-target = "x86_64-unknown-linux-gnu"
+targets = []
+
 [lints]
 workspace = true
 

src/lib.rs

@@ -1,7 +1,7 @@
 // Copyright 2023 the Vello Authors
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
-//! Render an SVG document to a Vello [`Scene`].
+//! Render an SVG document to a Vello [`Scene`](vello::Scene).
 //!
 //! This currently lacks support for a [number of important](crate#unsupported-features) SVG features.
 //!
@@ -23,6 +23,8 @@
 //! - path shape-rendering
 //! - patterns
 
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+
 mod render;
 
 mod error;
@@ -37,7 +39,7 @@ pub use vello;
 pub use usvg;
 use vello::kurbo::Affine;
 
-/// Render a [`Scene`] from an SVG string, with default error handling.
+/// Render a [`Scene`](vello::Scene) from an SVG string, with default error handling.
 ///
 /// This will draw a red box over (some) unsupported elements.
 pub fn render(svg: &str) -> Result<vello::Scene, Error> {
@@ -48,7 +50,7 @@ pub fn render(svg: &str) -> Result<vello::Scene, Error> {
     Ok(scene)
 }
 
-/// Append an SVG to a vello [`Scene`], with default error handling.
+/// Append an SVG to a vello [`Scene`](vello::Scene), with default error handling.
 ///
 /// This will draw a red box over (some) unsupported elements.
 pub fn append(scene: &mut vello::Scene, svg: &str) -> Result<(), Error> {
@@ -58,7 +60,7 @@ pub fn append(scene: &mut vello::Scene, svg: &str) -> Result<(), Error> {
     Ok(())
 }
 
-/// Append an SVG to a vello [`Scene`], with user-provided error handling logic.
+/// Append an SVG to a vello [`Scene`](vello::Scene), with user-provided error handling logic.
 ///
 /// See the [module level documentation](crate#unsupported-features) for a list of some unsupported svg features
 pub fn append_with<F: FnMut(&mut vello::Scene, &usvg::Node)>(
@@ -72,7 +74,7 @@ pub fn append_with<F: FnMut(&mut vello::Scene, &usvg::Node)>(
     Ok(())
 }
 
-/// Render a [`Scene`] from a [`usvg::Tree`], with default error handling.
+/// Render a [`Scene`](vello::Scene) from a [`usvg::Tree`], with default error handling.
 ///
 /// This will draw a red box over (some) unsupported elements.
 pub fn render_tree(svg: &usvg::Tree) -> vello::Scene {
@@ -81,14 +83,14 @@ pub fn render_tree(svg: &usvg::Tree) -> vello::Scene {
     scene
 }
 
-/// Append an [`usvg::Tree`]  to a vello [`Scene`], with default error handling.
+/// Append an [`usvg::Tree`] to a vello [`Scene`](vello::Scene), with default error handling.
 ///
 /// This will draw a red box over (some) unsupported elements.
 pub fn append_tree(scene: &mut vello::Scene, svg: &usvg::Tree) {
     append_tree_with(scene, svg, &mut util::default_error_handler);
 }
 
-/// Append an [`usvg::Tree`] to a vello [`Scene`], with user-provided error handling logic.
+/// Append an [`usvg::Tree`] to a vello [`Scene`](vello::Scene), with user-provided error handling logic.
 ///
 /// See the [module level documentation](crate#unsupported-features) for a list of some unsupported svg features
 pub fn append_tree_with<F: FnMut(&mut vello::Scene, &usvg::Node)>(

src/util.rs

@@ -183,7 +183,7 @@ pub fn to_brush(paint: &usvg::Paint, opacity: usvg::Opacity) -> Option<(Brush, A
     }
 }
 
-/// Error handler function for [`super::render_tree_with`] which draws a transparent red box
+/// Error handler function for [`super::append_tree_with`] which draws a transparent red box
 /// instead of unsupported SVG features
 pub fn default_error_handler(scene: &mut Scene, node: &usvg::Node) {
     let bb = node.bounding_box();