Add parley_engine usage example (#742)

LLM Contributions: Review

Based on #739.

This adds a brief introduction and a doctest usage example to
`parley_engine`. @Soundcreates proposed the initial wording in #739.
I've rebased that to be on top of recent API changes, plus made the
doctest compiled (but `no_run`, as otherwise a font needs to be
available, which I'm not sure is straightforward with a doctest).

Closes #714.

**Changelog: None**

---------

Co-authored-by: Shantanav <shantanav7@gmail.com>

Author: tomcur

parley_engine/README.md

@@ -24,12 +24,75 @@ See https://linebender.org/blog/doc-include/ for related discussion. -->
 
 <!-- cargo-rdme start -->
 
-Parley Engine provides low level APIs for implementing text layout.
+Parley Engine provides low level APIs for shaping paragraphs of text.
+
+## Usage
+
+Use [`Analyzer`], [`Analysis`], [`Shaper`] and [`ShapedText`] to shape a paragraph of text into
+glyphs. Correct reshaping of lines is in progress; in the meantime you can break text at
+[`Atom`] or [`ShapedCluster`][crate::shape::ShapedCluster] boundaries.
+
+Text analysis is performed before shaping, and the same source string must be passed to each
+stage.
+
+Higher-level users may prefer using [`parley`][parley], which uses this crate and implements
+layout and styling.
+
+```rust
+let mut analysis = Analysis::default();
+let mut analyzer = Analyzer::default();
+let mut shaped_text = ShapedText::default();
+let mut shaper = Shaper::default();
+
+let text = "The quick brown ثعلب jumps over the lazy dog.";
+let char_count = text.chars().count();
+let char_style_indices = vec![0; char_count];
+
+analyzer.analyze(text, &AnalysisOptions::default(), &mut analysis);
+shaper.shape_text(
+    text,
+    &analysis,
+    &char_style_indices,
+    [Item {
+        char_end: char_count.try_into().unwrap(),
+        options: ShapeOptions {
+            font_size: 16.0,
+            language: None,
+            features: &[],
+            variations: &[],
+        },
+     }],
+     select_font, // Selects fonts covering each cluster.
+     &mut shaped_text,
+);
+
+for (run_idx, run) in shaped_text.runs().iter().enumerate() {
+    let slice = shaped_text.run_slice(run_idx as u32);
+    // You can, for example, measure grapheme advances for hit-testing or
+    // placing carets.
+    for atom in slice.atoms_start() {
+        for grapheme in atom.graphemes_start() {
+            std::dbg!(grapheme);
+        }
+    }
+
+    // Or get glyphs for rendering (for simplicity, this iterates clusters in
+    // logical order, but for rendering you'd want to reorder runs and clusters
+    // according to their `run.bidi_level`).
+    for cluster in slice.shaped_clusters_range() {
+        for glyph in slice.shaped_cluster_glyphs(cluster) {
+            std::dbg!(glyph);
+        }
+    }
+}
+```
 
 ## Features
 
 - `std` (enabled by default): This is currently unused and is provided for forward compatibility.
 
+[parley]: https://docs.rs/parley
+
 <!-- cargo-rdme end -->
 
 ## Minimum supported Rust Version (MSRV)

parley_engine/src/lib.rs

@@ -1,11 +1,92 @@
 // Copyright 2025 the Parley Authors
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
-//! Parley Engine provides low level APIs for implementing text layout.
+//! Parley Engine provides low level APIs for shaping paragraphs of text.
+//!
+//! ## Usage
+//!
+//! Use [`Analyzer`], [`Analysis`], [`Shaper`] and [`ShapedText`] to shape a paragraph of text into
+//! glyphs. Correct reshaping of lines is in progress; in the meantime you can break text at
+//! [`Atom`] or [`ShapedCluster`][crate::shape::ShapedCluster] boundaries.
+//!
+//! Text analysis is performed before shaping, and the same source string must be passed to each
+//! stage.
+//!
+//! Higher-level users may prefer using [`parley`][parley], which uses this crate and implements
+//! layout and styling.
+//!
+//! ```rust,no_run
+//! # // We only compile this doctest because we don't have a font available.
+//! # use parley_engine::{Analysis, AnalysisOptions, Analyzer, FontInstance, FontSelector, ShapedText, ShapeOptions, Shaper};
+//! # use parley_engine::shape::CharCluster;
+//! # use parley_engine::itemize::{Item, Segment};
+//! #
+//! # struct NoFont;
+//! # impl FontSelector for NoFont {
+//! #     fn select_font(
+//! #         &mut self,
+//! #         _segment: &Segment,
+//! #         _options: &ShapeOptions<'_>,
+//! #         _cluster: &mut CharCluster,
+//! #     ) -> Option<FontInstance> {
+//! #         unimplemented!()
+//! #     }
+//! # }
+//! #
+//! # let select_font = NoFont;
+//! let mut analysis = Analysis::default();
+//! let mut analyzer = Analyzer::default();
+//! let mut shaped_text = ShapedText::default();
+//! let mut shaper = Shaper::default();
+//!
+//! let text = "The quick brown ثعلب jumps over the lazy dog.";
+//! let char_count = text.chars().count();
+//! let char_style_indices = vec![0; char_count];
+//!
+//! analyzer.analyze(text, &AnalysisOptions::default(), &mut analysis);
+//! shaper.shape_text(
+//!     text,
+//!     &analysis,
+//!     &char_style_indices,
+//!     [Item {
+//!         char_end: char_count.try_into().unwrap(),
+//!         options: ShapeOptions {
+//!             font_size: 16.0,
+//!             language: None,
+//!             features: &[],
+//!             variations: &[],
+//!         },
+//!      }],
+//!      select_font, // Selects fonts covering each cluster.
+//!      &mut shaped_text,
+//! );
+//!
+//! for (run_idx, run) in shaped_text.runs().iter().enumerate() {
+//!     let slice = shaped_text.run_slice(run_idx as u32);
+//!     // You can, for example, measure grapheme advances for hit-testing or
+//!     // placing carets.
+//!     for atom in slice.atoms_start() {
+//!         for grapheme in atom.graphemes_start() {
+//!             std::dbg!(grapheme);
+//!         }
+//!     }
+//!
+//!     // Or get glyphs for rendering (for simplicity, this iterates clusters in
+//!     // logical order, but for rendering you'd want to reorder runs and clusters
+//!     // according to their `run.bidi_level`).
+//!     for cluster in slice.shaped_clusters_range() {
+//!         for glyph in slice.shaped_cluster_glyphs(cluster) {
+//!             std::dbg!(glyph);
+//!         }
+//!     }
+//! }
+//! ```
 //!
 //! ## Features
 //!
 //! - `std` (enabled by default): This is currently unused and is provided for forward compatibility.
+//!
+//! [parley]: https://docs.rs/parley
 
 // LINEBENDER LINT SET - lib.rs - v3
 // See https://linebender.org/wiki/canonical-lints/