Some layout documentation

1 files changed, 64 insertions, 0 deletions

diff --git a/library/src/layout/grid.rs b/library/src/layout/grid.rs
index eb45cfbe..85d464b1 100644
--- a/library/src/layout/grid.rs
+++ b/library/src/layout/grid.rs
@@ -5,19 +5,83 @@ use super::Spacing;
 /// # Grid
 /// Arrange content in a grid.
 ///
+/// The grid element allows you to arrange content in a grid. You can define the
+/// number of rows and columns, as well as the size of the gutters between them.
+/// There are multiple sizing modes for columns and rows, including fixed sizes,
+/// that can be used to create complex layouts.
+///
+/// The sizing of the grid is determined by the track sizes specified in the
+/// arguments. Because each of the sizing parameters accepts the same values, we
+/// will explain them here:
+///
+/// Each sizing argument accepts an array of track sizes. A track size is either
+/// - a fixed length (e.g. `10pt`). The track will be exactly this size.
+/// - `{auto}`. The track will be sized to fit its contents. It will be at most
+///   as large as the remaining space. If there is more than one `auto` track
+///   that, together, claim more than the available space, they will be resized
+///   to fit the available space.
+/// - a `fractional` length (e.g. `{1fr}`). Once all other tracks have been
+///   sized, the remaining space will be divided among the fractional tracks
+///   according to their fraction. For example, if there are two fractional
+///   tracks, each with a fraction of `1`, they will each take up half of the
+///   remaining space.
+///
+/// To specify a single track, the array can be omitted in favor of a single
+/// value. To specify multiple `{auto}` tracks, enter the number of tracks
+/// instead of a value. For example, `columns: {3}` is equivalent to
+/// `columns: {(auto, auto, auto)}`.
+///
+/// ## Example
+/// ```
+/// #set text(hyphenate: true)
+/// #let cell = rect.with(
+///     inset: 6pt,
+///     fill: rgb("e4e5ea"),
+///     width: 100%,
+///     radius: 6pt
+///   )
+///   
+///   #grid(
+///     columns: (60pt, 1fr, 60pt),
+///     rows: (60pt, auto),
+///     gutter: 3pt,
+///     cell(height: 100%)[*Easy to learn*],
+///     cell(height: 100%)[Great output],
+///     cell(height: 100%)[*Intuitive*],
+///     cell[*Our best Typst yet*],
+///     cell[
+///       Responsive design in print
+///       for everyone
+///     ],
+///     cell[*One more thing...*],
+///   )
+/// ```
+///
 /// ## Parameters
 /// - cells: Content (positional, variadic)
 ///   The contents of the table cells.
 ///
+///   The cells are populated in row-major order.
+///
 /// - rows: TrackSizings (named)
 ///   Defines the row sizes.
 ///
+///   If there are more cells than fit the defined rows, the last row is
+///   repeated until there are no more cells.
+///
 /// - columns: TrackSizings (named)
 ///   Defines the column sizes.
 ///
+///   Either specify a track size array or provide an
+///   integer to create a grid with that many `{auto}`-sized columns. Note that
+///   opposed to rows and gutters, providing a single track size will only ever
+///   create a single column.
+///
 /// - gutter: TrackSizings (named)
 ///   Defines the gaps between rows & columns.
 ///
+///   If there are more gutters than defined sizes, the last gutter is repeated.
+///
 /// - column-gutter: TrackSizings (named)
 ///   Defines the gaps between columns. Takes precedence over `gutter`.
 ///