More clearly mark Vello API as an experiment/preview

.github/workflows/ci.yml

@@ -113,7 +113,7 @@ jobs:
         run: cargo rdme --check --workspace-project=vello_common
 
       - name: Run cargo rdme (vello_api)
-        run: cargo rdme --check --heading-base-level=0 --workspace-project=vello_api
+        run: cargo rdme --check --workspace-project=vello_api
 
       - name: Run cargo rdme (vello_hybrid)
         run: cargo rdme --check --workspace-project=vello_hybrid

sparse_strips/vello_api/README.md

@@ -2,7 +2,7 @@
 
 # Vello API
 
-**Public API types**
+**Experimental public API for Vello Renderers**
 
 [![Latest published version.](https://img.shields.io/crates/v/vello_api.svg)](https://crates.io/crates/vello_api)
 [![Documentation build status.](https://img.shields.io/docsrs/vello_api.svg)](https://docs.rs/vello_api)
@@ -16,7 +16,7 @@
 
 <!-- We use cargo-rdme to update the README with the contents of lib.rs.
 To edit the following section, update it in lib.rs, then run:
-cargo rdme --workspace-project=vello_api --heading-base-level=0
+cargo rdme --workspace-project=vello_api
 Full documentation at https://github.com/orium/cargo-rdme -->
 
 <!-- Intra-doc links used in lib.rs should be evaluated here.
@@ -26,18 +26,21 @@ See https://linebender.org/blog/doc-include/ for related discussion. -->
 
 <!-- cargo-rdme start -->
 
-Vello API is the rendering API of the 2D renderers in the Vello project.
+Vello API is the **experimental** rendering API of the 2D renderers in the Vello project.
+
+Warning: Vello API is currently only released as a preview, and is not ready for usage beyond short-term experiments.
+We know of several design decisions which will change before its use can be recommended.
 
 There are currently two [supported Vello renderers](#renderers), each with different tradeoffs.
 This crate allows you to write the majority of your application logic to support either of those renderers.
 These renderers are [Vello CPU](todo) and [Vello Hybrid](todo).
 
-# Usage
+## Usage
 
 TODO: Mention Renderer trait when it exists. Otherwise, this code isn't really usable yet.
 TODO: This is a stub just to have an outline to push.
 
-# Renderers
+## Renderers
 
 The Vello renderers which support this API are:
 
@@ -65,7 +68,7 @@ Vello API guarantees identical rendering between renderers which implement it, b
 This doesn't apply to renderer-specific features.
 <!-- TODO: Is ^ true? -->
 
-# Abstraction Boundaries
+## Abstraction Boundaries
 
 The abstractions in this crate are focused on 2D rendering, and the resources required to perform that.
 In particular, this does not abstract over strategies for:
@@ -78,7 +81,7 @@ These functionalities are however catered for where applicable by APIs on the sp
 The renderer API supports downcasting to the specific renderer, so that these extensions can be called.
 Each supported renderer will/does have examples showing how to achieve this yourself.
 
-# Text
+## Text
 
 Vello API does not handle text/glyph rendering itself.
 This allows for improved resource sharing of intermediate text layout data, for hinting and ink splitting underlines.
@@ -88,15 +91,15 @@ Note that this crate is not currently implemented; design work is ongoing.
 We also support rendering using using traditional glyph atlases, which may be preferred by some consumers.
 This is especially useful to achieve subpixel rendering, such as ClearType, which Vello doesn't currently support directly.
 
-# Unimplemented Features
+## Unimplemented Features
 
 NOTE: This section is not complete; in particular, we have only pushed a half-version of this API to make review more scoped.
 
 The current version of Vello API is a minimal viable product for exploration and later expansion.
 As such, there are several features which we expect to be included in this API, but which are not yet exposed in this crate.
 These are categorised as follows:
 
-## Out of scope/Renderer specific
+### Out of scope/Renderer specific
 
 <!-- This section can be removed once the other three classes are empty -->
 As discussed above, some features are out-of-scope, as they have concerns which need to be handled individually by each renderer.
@@ -105,7 +108,7 @@ This includes:
 - Rendering directly to a surface.
 - Importing "external" textures (e.g. from a `wgpu::Texture`)
 
-## Excluded for expedience
+### Excluded for expedience
 
 - Renderer specific painting commands (i.e. using downcasting).
   This is intended to be an immediate follow-up to the MVP landing.
@@ -122,7 +125,7 @@ This includes:
 - "Unsetting" the brush; this is mostly useful for append style operations, which may unexpectedly change the brush.
 - Dynamic version of `PaintScene`, allowing `dyn PaintScene` for cases where that would be relevant.
 
-## Not cross-renderer
+### Not cross-renderer
 
 There are some features which are only implemented in one of our target renderers, so cannot yet be included in the generalised API.
 As an interim solution, we intend to expose these features as renderer specific extensions (see the "excluded for expedience section").
@@ -136,7 +139,7 @@ For Vello CPU, these are (i.e. Vello Hybrid does not implement these):
 
 There are currently no such features the other way around (i.e. which only Vello Hybrid supports).
 
-## Not implemented
+### Not implemented
 
 - Path caching. This feature is intended to allow re-using paths efficiently, primarily for glyphs.
 - Blurred rounded rectangle paints in custom shapes (e.g. to exclude the unblurred parts).

sparse_strips/vello_api/src/lib.rs

@@ -6,7 +6,10 @@
 
 // These docs are written for a more complete version of Vello API.
 
-//! Vello API is the rendering API of the 2D renderers in the Vello project.
+//! Vello API is the **experimental** rendering API of the 2D renderers in the Vello project.
+//!
+//! Warning: Vello API is currently only released as a preview, and is not ready for usage beyond short-term experiments.
+//! We know of several design decisions which will change before its use can be recommended.
 //!
 //! There are currently two [supported Vello renderers](#renderers), each with different tradeoffs.
 //! This crate allows you to write the majority of your application logic to support either of those renderers.

sparse_strips/vello_api/src/painter.rs

@@ -57,7 +57,6 @@ pub type StandardBrush = Brush<ImageBrush<TextureId>>;
 /// [`append`]: PaintScene::append
 /// [`Renderer`]: todo
 pub trait PaintScene: Any {
-    // TODO: This also "clobbers" the brush; we need to document that.
     /// Insert the contents of `Scene` into the drawing sequence at this point, with the 2d affine
     /// `transform` applied to its contents.
     ///

sparse_strips/vello_common/README.md

@@ -16,7 +16,7 @@
 
 <!-- We use cargo-rdme to update the README with the contents of lib.rs.
 To edit the following section, update it in lib.rs, then run:
-cargo rdme --workspace-project=vello_common --heading-base-level=0
+cargo rdme --workspace-project=vello_common
 Full documentation at https://github.com/orium/cargo-rdme -->
 
 <!-- Intra-doc links used in lib.rs should be evaluated here.

sparse_strips/vello_cpu/src/api.rs

@@ -1,7 +1,14 @@
 // Copyright 2025 the Vello Authors
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
-//! Integration of Vello API into Vello CPU.
+//! Integration of the experimental Vello API preview into Vello CPU.
+//!
+//! <div class="warning">
+//!
+//! Vello API is currently in an experimental phase, released only as a preview, and has no stability guarantees.
+//! See [its documentation](vello_api) for more details.
+//!
+//! </div>
 
 use vello_api::{
     PaintScene, Scene,

sparse_strips/vello_hybrid/src/api.rs

@@ -1,7 +1,14 @@
 // Copyright 2025 the Vello Authors
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
-//! Integration of Vello API into Vello Hybrid.
+//! Integration of the experimental Vello API preview into Vello Hybrid.
+//!
+//! <div class="warning">
+//!
+//! Vello API is currently in an experimental phase, released only as a preview, and has no stability guarantees.
+//! See [its documentation](vello_api) for more details.
+//!
+//! </div>
 
 use vello_api::{
     PaintScene, Scene,