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

* 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.
* Target only `x86_64-unknown-linux-gnu` on docs.rs as we don't have any
platform specific docs.
* Properly enable example scraping for `xilem`, `xilem_core`, and
`masonry`. Fully disable it for `xilem_web` which does not have examples
as Cargo defines them.
* Pass `--all-features` at docs.rs to match our CI and reduce the
maintenance burden of manually syncing the features list.
* 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.
* Replaced `[!TIP]` with `💡 Tip` that was inside `<div
class="rustdoc-hidden" />`. The GitHub specific tip causes a `rustdoc`
error and [didn't even render
properly](https://github.com/linebender/xilem/blob/ac2ca3878501749f55068529de904ad9b24b8a54/masonry/src/doc/01_creating_app.md).
* Updated `01_creating_app.md` just enough to get `rustdoc` to pass, but
that file needs a bunch of more work, as it is outdated.

.github/workflows/ci.yml

@@ -388,15 +388,17 @@ jobs:
         with:
           save-if: ${{ github.event_name != 'merge_group' }}
 
-      # We test documentation using nightly to match docs.rs. This prevents potential breakages
+      # We test documentation using nightly to match docs.rs.
       - name: cargo doc
         run: cargo doc --workspace --locked --all-features --no-deps --document-private-items -Zunstable-options -Zrustdoc-scrape-examples
+        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

masonry/Cargo.toml

@@ -13,6 +13,9 @@ rust-version.workspace = true
 
 [package.metadata.docs.rs]
 all-features = true
+# There are no platform specific docs.
+default-target = "x86_64-unknown-linux-gnu"
+targets = []
 # rustdoc-scrape-examples tracking issue https://github.com/rust-lang/rust/issues/88791
 cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
 
@@ -70,9 +73,12 @@ tempfile = "3.10.1"
 # Make wgpu use tracing for its spans.
 profiling = { version = "1.0.15", features = ["profile-with-tracing"] }
 
+[target.'cfg(target_os = "android")'.dependencies]
+tracing_android_trace = "0.1.0"
+
 [[example]]
 name = "simple_image"
 #required-features = ["image", "png"]
-
-[target.'cfg(target_os = "android")'.dependencies]
-tracing_android_trace = "0.1.0"
+# This actually enables scraping for all examples, not just this one.
+# However it is possible to set doc-scrape-examples to false for other specific examples.
+doc-scrape-examples = true

masonry/src/doc/01_creating_app.md

@@ -5,7 +5,7 @@
 
 <div class="rustdoc-hidden">
 
-> [!TIP]
+> 💡 Tip
 >
 > This file is intended to be read in rustdoc.
 > Use `cargo doc --open --package masonry --no-deps`.
@@ -78,10 +78,9 @@ That method gives our app a [`DriverCtx`] context, which we can use to access th
 
 We create a `Driver` struct to store a very simple app's state, and we implement the `AppDriver` trait for it:
 
-```rust,ignore
-use masonry::app_driver::{AppDriver, DriverCtx};
-use masonry::{Action, WidgetId};
-use masonry::widget::{Label};
+```rust
+use masonry::{Action, AppDriver, DriverCtx, WidgetId};
+use masonry::widget::{Flex, Label, Portal, RootWidget, WidgetMut};
 
 struct Driver {
     next_task: String,
@@ -92,9 +91,9 @@ impl AppDriver for Driver {
         match action {
             Action::ButtonPressed(_) => {
                 let mut root: WidgetMut<RootWidget<Portal<Flex>>> = ctx.get_root();
-                let mut portal = root.child_mut();
-                let mut flex = portal.child_mut();
-                flex.add_child(Label::new(self.next_task.clone()));
+                let mut portal = RootWidget::child_mut(&mut root);
+                let mut flex = Portal::child_mut(&mut portal);
+                Flex::add_child(&mut flex, Label::new(self.next_task.clone()));
             }
             Action::TextChanged(new_text) => {
                 self.next_task = new_text.clone();
@@ -121,7 +120,7 @@ When handling `ButtonPressed`:
 A [`WidgetMut`] is a smart reference type which lets us modify the widget tree.
 It's set up to automatically propagate update flags and update internal state when dropped.
 
-We use [`WidgetMut::<Flex>::add_child()`][add_child] to add a new `Label` with the text of our new task to our list.
+We use [`Flex::add_child()`][add_child] to add a new `Label` with the text of our new task to our list.
 
 In our main function, we create a `Driver` and pass it to `event_loop_runner::run`:
 
@@ -260,4 +259,4 @@ Most of this documentation is written to help developers trying to build such a
 [`DriverCtx`]: crate::DriverCtx
 [`WidgetId`]: crate::WidgetId
 [`WidgetMut`]: crate::widget::WidgetMut
-[add_child]: crate::widget::WidgetMut::add_child
+[add_child]: crate::widget::Flex::add_child

masonry/src/doc/02_implementing_widget.md

@@ -5,7 +5,7 @@
 
 <div class="rustdoc-hidden">
 
-> [!TIP]
+> 💡 Tip
 >
 > This file is intended to be read in rustdoc.
 > Use `cargo doc --open --package masonry --no-deps`.

masonry/src/doc/03_implementing_container_widget.md

@@ -5,7 +5,7 @@
 
 <div class="rustdoc-hidden">
 
-> [!TIP]
+> 💡 Tip
 >
 > This file is intended to be read in rustdoc.
 > Use `cargo doc --open --package masonry --no-deps`.

masonry/src/doc/04_testing_widget.md

@@ -5,7 +5,7 @@
 
 <div class="rustdoc-hidden">
 
-> [!TIP]
+> 💡 Tip
 >
 > This file is intended to be read in rustdoc.
 > Use `cargo doc --open --package masonry --no-deps`.

masonry/src/doc/05_pass_system.md

@@ -5,7 +5,7 @@
 
 <div class="rustdoc-hidden">
 
-> [!TIP]
+> 💡 Tip
 >
 > This file is intended to be read in rustdoc.
 > Use `cargo doc --open --package masonry --no-deps`.

masonry/src/doc/06_masonry_concepts.md

@@ -5,7 +5,7 @@
 
 <div class="rustdoc-hidden">
 
-> [!TIP]
+> 💡 Tip
 >
 > This file is intended to be read in rustdoc.
 > Use `cargo doc --open --package masonry --no-deps`.

masonry/src/lib.rs

@@ -99,6 +99,7 @@
 #![allow(clippy::should_implement_trait)]
 #![allow(clippy::single_match)]
 #![cfg_attr(docsrs, feature(doc_cfg))]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 #![cfg_attr(not(debug_assertions), allow(unused))]
 // False-positive with dev-dependencies only used in examples
 #![cfg_attr(not(test), warn(unused_crate_dependencies))]

xilem/Cargo.toml

@@ -13,11 +13,17 @@ exclude = ["/resources/fonts/roboto_flex/", "/resources/data/http_cats_status/"]
 
 [package.metadata.docs.rs]
 all-features = true
+# There are no platform specific docs.
+default-target = "x86_64-unknown-linux-gnu"
+targets = []
 # rustdoc-scrape-examples tracking issue https://github.com/rust-lang/rust/issues/88791
 cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
 
 [[example]]
 name = "mason"
+# This actually enables scraping for all examples, not just this one.
+# However it is possible to set doc-scrape-examples to false for other specific examples.
+doc-scrape-examples = true
 
 # Also add to ANDROID_TARGETS in .github/ci.yml if adding a new Android example
 [[example]]

xilem/src/lib.rs

@@ -3,6 +3,7 @@
 
 // False-positive with dev-dependencies only used in examples
 #![cfg_attr(not(test), warn(unused_crate_dependencies))]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 #![warn(unnameable_types, unreachable_pub)]
 #![warn(clippy::print_stdout, clippy::print_stderr, clippy::dbg_macro)]
 

xilem/src/one_of.rs

@@ -1,7 +1,7 @@
 // Copyright 2024 the Xilem Authors
 // SPDX-License-Identifier: Apache-2.0
 
-//! Statically typed alternatives to the type-erased [`AnyView`](`crate::AnyView`).
+//! Statically typed alternatives to the type-erased [`AnyWidgetView`](`crate::any_view::AnyWidgetView`).
 
 use accesskit::{NodeBuilder, Role};
 use masonry::{

xilem_core/Cargo.toml

@@ -11,19 +11,26 @@ rust-version.workspace = true
 
 publish = false # We'll publish this alongside Xilem 0.2
 
+[package.metadata.docs.rs]
+all-features = true
+# There are no platform specific docs.
+default-target = "x86_64-unknown-linux-gnu"
+targets = []
+# rustdoc-scrape-examples tracking issue https://github.com/rust-lang/rust/issues/88791
+cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
+
 [features]
 kurbo = ["dep:kurbo"]
 
-
 [dependencies]
 tracing.workspace = true
 kurbo = { optional = true, workspace = true }
 
 [lints]
 workspace = true
 
-[package.metadata.docs.rs]
-default-target = "x86_64-unknown-linux-gnu"
-# xilem_core is entirely platform-agnostic, so only display docs for one platform
-targets = []
-features = ["kurbo"]
+[[example]]
+name = "user_interface"
+# This actually enables scraping for all examples, not just this one.
+# However it is possible to set doc-scrape-examples to false for other specific examples.
+doc-scrape-examples = true

xilem_core/src/deferred.rs

@@ -8,7 +8,7 @@ use core::marker::PhantomData;
 
 use crate::{DynMessage, Message, NoElement, View, ViewId, ViewPathTracker};
 
-/// A `Context` for a [`View`](crate::View) implementation which supports
+/// A `Context` for a [`View`] implementation which supports
 /// asynchronous message reporting.
 pub trait AsyncCtx<Message = DynMessage>: ViewPathTracker {
     /// Get a [`RawProxy`] for this context.
@@ -29,13 +29,13 @@ pub trait AsyncCtx<Message = DynMessage>: ViewPathTracker {
 ///
 /// ## Lifetimes
 ///
-/// It is valid for a [`RawProxy`] to outlive the [`View`](crate::View) it is associated with.
+/// It is valid for a [`RawProxy`] to outlive the [`View`] it is associated with.
 pub trait RawProxy<Message = DynMessage>: Send + Sync + 'static {
     /// Send a `message` to the view at `path` in this driver.
     ///
     /// Note that it is only valid to send messages to views which expect
     /// them, of the type they expect.
-    /// It is expected for [`View`](crate::View)s to panic otherwise, and the routing
+    /// It is expected for [`View`]s to panic otherwise, and the routing
     /// will prefer to send stable.
     ///
     /// # Errors
@@ -105,7 +105,7 @@ pub enum ProxyError {
     ///
     /// TODO: Should this also support a source message?
     DriverFinished(DynMessage),
-    /// The [`View`](crate::View) the message was being routed to is no longer in the view tree.
+    /// The [`View`] the message was being routed to is no longer in the view tree.
     ///
     /// This likely requires async error handling to happen.
     ViewExpired(DynMessage, Arc<[ViewId]>),

xilem_core/src/lib.rs

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 #![cfg_attr(not(test), no_std)]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 #![forbid(unsafe_code)]
 #![warn(missing_docs, unreachable_pub, unused_crate_dependencies)]
 #![warn(clippy::print_stdout, clippy::print_stderr, clippy::dbg_macro)]

xilem_core/src/sequence.rs

@@ -338,7 +338,7 @@ where
 /// We use a generation arena for vector types, with half of the `ViewId` dedicated
 /// to the index, and the other half used for the generation.
 ///
-// This is managed in [`create_vector_view_id`] and [`view_id_to_index_generation`]
+// This is managed in [`create_generational_view_id`] and [`view_id_to_index_generation`]
 #[doc(hidden)]
 #[allow(unnameable_types)] // reason: Implementation detail, public because of trait visibility rules
 pub struct VecViewState<InnerState> {
@@ -360,7 +360,7 @@ fn create_generational_view_id(index: usize, generation: u32) -> ViewId {
     ViewId::new(id_high | id_low)
 }
 
-/// Undoes [`create_vector_view_id`]
+/// Undoes [`create_generational_view_id`]
 fn view_id_to_index_generation(view_id: ViewId) -> (usize, u32) {
     #![allow(clippy::cast_possible_truncation)]
     let view_id = view_id.routing_id();

xilem_web/Cargo.toml

@@ -13,8 +13,9 @@ rust-version.workspace = true
 
 [package.metadata.docs.rs]
 all-features = true
-# rustdoc-scrape-examples tracking issue https://github.com/rust-lang/rust/issues/88791
-cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
+# There are no platform specific docs.
+default-target = "x86_64-unknown-linux-gnu"
+targets = []
 
 [lints]
 workspace = true

xilem_web/src/elements.rs

@@ -17,7 +17,7 @@ use crate::{
 };
 
 // sealed, because this should only cover `ViewSequences` with the blanket impl below
-/// This is basically a specialized dynamically dispatchable [`ViewSequence`], It's currently not able to change the underlying type unlike [`AnyDomView`](crate::AnyDomView), so it should not be used as `dyn DomViewSequence`.
+/// This is basically a specialized dynamically dispatchable [`ViewSequence`][crate::core::ViewSequence], It's currently not able to change the underlying type unlike [`AnyDomView`](crate::AnyDomView), so it should not be used as `dyn DomViewSequence`.
 /// It's mostly a hack to avoid a completely static view tree, which unfortunately brings rustc (type-checking) down to its knees and results in long compile-times
 pub(crate) trait DomViewSequence<State, Action>: 'static {
     /// Get an [`Any`] reference to `self`.

xilem_web/src/lib.rs

@@ -11,6 +11,7 @@
 //! .rustdoc-hidden { display: none; }
 //! </style>
 #![doc = include_str!("../README.md")]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
 use std::{any::Any, ops::Deref as _};
 

xilem_web/src/pod.rs

@@ -193,7 +193,7 @@ impl PodFlags {
         }
     }
 
-    /// This should only be used in tests, other than within the [`Element`] props
+    /// This should only be used in tests, other than within the element props
     pub(crate) fn clear(&mut self) {
         self.0 = 0;
     }