Factor out boilerplate sessions

Author: chiphogg

BUILD.bazel

@@ -31,13 +31,16 @@ py_binary(
         "mkdocs.yml",
         ":au_all_units_hh",
         ":au_all_units_noio_hh",
+        ":au_all_units_stdformat_hh",
+        ":au_all_units_stdformat_noio_hh",
         ":au_hh",
         ":au_noio_hh",
         ":au_stdformat_hh",
         ":au_stdformat_noio_hh",
-        ":au_all_units_stdformat_hh",
-        ":au_all_units_stdformat_noio_hh",
-    ] + glob(["docs/**"]),
+    ] + glob([
+        "docs/**",
+        "doc_snippets/**",
+    ]),
     deps = [
         requirement("mkdocs"),
         requirement("mkdocs-material"),
@@ -51,13 +54,16 @@ py_binary(
         "mkdocs.yml",
         ":au_all_units_hh",
         ":au_all_units_noio_hh",
+        ":au_all_units_stdformat_hh",
+        ":au_all_units_stdformat_noio_hh",
         ":au_hh",
         ":au_noio_hh",
         ":au_stdformat_hh",
         ":au_stdformat_noio_hh",
-        ":au_all_units_stdformat_hh",
-        ":au_all_units_stdformat_noio_hh",
-    ] + glob(["docs/**"]),
+    ] + glob([
+        "docs/**",
+        "doc_snippets/**",
+    ]),
     main = "mike_bin.py",
     deps = [
         ":update_docs",

doc_snippets/lifetime-risk-lazy.md

@@ -0,0 +1,5 @@
+!!! warning "Lifetime risk"
+    This operation is **lazy**: its result is an expression template, which refers to its operands
+    instead of owning its own copy of the data.  The result is valid only as long as its operands
+    are alive.  If it needs to outlive them, materialize it with [`eval()`](./eigen.md#eval).  See
+    our [Eigen safety guide](../discussion/concepts/eigen_safety.md) to learn more.

doc_snippets/lifetime-risk-maybe-lazy.md

@@ -0,0 +1,5 @@
+!!! warning "Lifetime risk"
+    If the result of this operation is an Eigen expression template, it refers to its operands
+    instead of owning its own copy of the data.  The result is valid only as long as its operands
+    are alive.  If it needs to outlive them, materialize it with [`eval()`](./eigen.md#eval).  See
+    our [Eigen safety guide](../discussion/concepts/eigen_safety.md) to learn more.

docs/reference/eigen.md

@@ -186,11 +186,7 @@ template <typename V, typename U, typename R>
 auto cross(const V &a, const Quantity<U, R> &b);
 ```
 
-!!! warning "Lifetime risk"
-    This operation is **lazy**: its result is an expression template, which refers to its operands
-    instead of owning its own copy of the data.  The result is valid only as long as its operands
-    are alive.  If it needs to outlive them, materialize it with [`eval()`](#eval).  See our
-    [Eigen safety guide](../discussion/concepts/eigen_safety.md) to learn more.
+--8<-- "lifetime-risk-lazy.md"
 
 ### `normalized`
 
@@ -225,11 +221,7 @@ template <typename V, typename U, typename R>
 auto cwiseProduct(const V &a, const Quantity<U, R> &b);
 ```
 
-!!! warning "Lifetime risk"
-    This operation is **lazy**: its result is an expression template, which refers to its operands
-    instead of owning its own copy of the data.  The result is valid only as long as its operands
-    are alive.  If it needs to outlive them, materialize it with [`eval()`](#eval).  See our
-    [Eigen safety guide](../discussion/concepts/eigen_safety.md) to learn more.
+--8<-- "lifetime-risk-lazy.md"
 
 ### `cwiseQuotient`
 
@@ -249,11 +241,7 @@ template <typename V, typename U, typename R>
 auto cwiseQuotient(const V &a, const Quantity<U, R> &b);
 ```
 
-!!! warning "Lifetime risk"
-    This operation is **lazy**: its result is an expression template, which refers to its operands
-    instead of owning its own copy of the data.  The result is valid only as long as its operands
-    are alive.  If it needs to outlive them, materialize it with [`eval()`](#eval).  See our
-    [Eigen safety guide](../discussion/concepts/eigen_safety.md) to learn more.
+--8<-- "lifetime-risk-lazy.md"
 
 ### `cwiseAbs`
 
@@ -264,11 +252,7 @@ template <typename U, typename R>
 auto cwiseAbs(const Quantity<U, R> &q);
 ```
 
-!!! warning "Lifetime risk"
-    This operation is **lazy**: its result is an expression template, which refers to its operands
-    instead of owning its own copy of the data.  The result is valid only as long as its operands
-    are alive.  If it needs to outlive them, materialize it with [`eval()`](#eval).  See our
-    [Eigen safety guide](../discussion/concepts/eigen_safety.md) to learn more.
+--8<-- "lifetime-risk-lazy.md"
 
 ### `cwiseSqrt`
 
@@ -279,11 +263,7 @@ template <typename U, typename R>
 auto cwiseSqrt(const Quantity<U, R> &q);
 ```
 
-!!! warning "Lifetime risk"
-    This operation is **lazy**: its result is an expression template, which refers to its operands
-    instead of owning its own copy of the data.  The result is valid only as long as its operands
-    are alive.  If it needs to outlive them, materialize it with [`eval()`](#eval).  See our
-    [Eigen safety guide](../discussion/concepts/eigen_safety.md) to learn more.
+--8<-- "lifetime-risk-lazy.md"
 
 ## Views and accessors
 
@@ -298,11 +278,7 @@ template <typename U, typename R>
 auto transpose(const Quantity<U, R> &q);
 ```
 
-!!! warning "Lifetime risk"
-    This operation is **lazy**: its result is an expression template, which refers to its operands
-    instead of owning its own copy of the data.  The result is valid only as long as its operands
-    are alive.  If it needs to outlive them, materialize it with [`eval()`](#eval).  See our
-    [Eigen safety guide](../discussion/concepts/eigen_safety.md) to learn more.
+--8<-- "lifetime-risk-lazy.md"
 
 ### `diagonal`
 
@@ -317,11 +293,7 @@ template <typename U, typename R>
 auto diagonal(const Quantity<U, R> &q, std::ptrdiff_t index);
 ```
 
-!!! warning "Lifetime risk"
-    This operation is **lazy**: its result is an expression template, which refers to its operands
-    instead of owning its own copy of the data.  The result is valid only as long as its operands
-    are alive.  If it needs to outlive them, materialize it with [`eval()`](#eval).  See our
-    [Eigen safety guide](../discussion/concepts/eigen_safety.md) to learn more.
+--8<-- "lifetime-risk-lazy.md"
 
 ### `row`, `col`
 
@@ -335,11 +307,7 @@ template <typename U, typename R>
 auto col(const Quantity<U, R> &q, std::ptrdiff_t j);
 ```
 
-!!! warning "Lifetime risk"
-    This operation is **lazy**: its result is an expression template, which refers to its operands
-    instead of owning its own copy of the data.  The result is valid only as long as its operands
-    are alive.  If it needs to outlive them, materialize it with [`eval()`](#eval).  See our
-    [Eigen safety guide](../discussion/concepts/eigen_safety.md) to learn more.
+--8<-- "lifetime-risk-lazy.md"
 
 ### `reverse`
 
@@ -350,11 +318,7 @@ template <typename U, typename R>
 auto reverse(const Quantity<U, R> &q);
 ```
 
-!!! warning "Lifetime risk"
-    This operation is **lazy**: its result is an expression template, which refers to its operands
-    instead of owning its own copy of the data.  The result is valid only as long as its operands
-    are alive.  If it needs to outlive them, materialize it with [`eval()`](#eval).  See our
-    [Eigen safety guide](../discussion/concepts/eigen_safety.md) to learn more.
+--8<-- "lifetime-risk-lazy.md"
 
 ### `conjugate`
 
@@ -365,11 +329,7 @@ template <typename U, typename R>
 auto conjugate(const Quantity<U, R> &q);
 ```
 
-!!! warning "Lifetime risk"
-    This operation is **lazy**: its result is an expression template, which refers to its operands
-    instead of owning its own copy of the data.  The result is valid only as long as its operands
-    are alive.  If it needs to outlive them, materialize it with [`eval()`](#eval).  See our
-    [Eigen safety guide](../discussion/concepts/eigen_safety.md) to learn more.
+--8<-- "lifetime-risk-lazy.md"
 
 ### `head`, `tail`, `segment`
 
@@ -397,11 +357,7 @@ template <typename U, typename R>
 auto segment(const Quantity<U, R> &q, std::ptrdiff_t start, std::ptrdiff_t n);
 ```
 
-!!! warning "Lifetime risk"
-    This operation is **lazy**: its result is an expression template, which refers to its operands
-    instead of owning its own copy of the data.  The result is valid only as long as its operands
-    are alive.  If it needs to outlive them, materialize it with [`eval()`](#eval).  See our
-    [Eigen safety guide](../discussion/concepts/eigen_safety.md) to learn more.
+--8<-- "lifetime-risk-lazy.md"
 
 ### `block`
 
@@ -421,11 +377,7 @@ auto block(const Quantity<U, R> &q,
            std::ptrdiff_t cols);
 ```
 
-!!! warning "Lifetime risk"
-    This operation is **lazy**: its result is an expression template, which refers to its operands
-    instead of owning its own copy of the data.  The result is valid only as long as its operands
-    are alive.  If it needs to outlive them, materialize it with [`eval()`](#eval).  See our
-    [Eigen safety guide](../discussion/concepts/eigen_safety.md) to learn more.
+--8<-- "lifetime-risk-lazy.md"
 
 ### `replicate`
 
@@ -441,11 +393,7 @@ template <typename U, typename R>
 auto replicate(const Quantity<U, R> &q, std::ptrdiff_t row_factor, std::ptrdiff_t col_factor);
 ```
 
-!!! warning "Lifetime risk"
-    This operation is **lazy**: its result is an expression template, which refers to its operands
-    instead of owning its own copy of the data.  The result is valid only as long as its operands
-    are alive.  If it needs to outlive them, materialize it with [`eval()`](#eval).  See our
-    [Eigen safety guide](../discussion/concepts/eigen_safety.md) to learn more.
+--8<-- "lifetime-risk-lazy.md"
 
 ## Matrix operations
 
@@ -459,8 +407,4 @@ template <typename U, typename R>
 auto inverse(const Quantity<U, R> &q);
 ```
 
-!!! warning "Lifetime risk"
-    This operation is **lazy**: its result is an expression template, which refers to its operands
-    instead of owning its own copy of the data.  The result is valid only as long as its operands
-    are alive.  If it needs to outlive them, materialize it with [`eval()`](#eval).  See our
-    [Eigen safety guide](../discussion/concepts/eigen_safety.md) to learn more.
+--8<-- "lifetime-risk-lazy.md"

docs/reference/quantity.md

@@ -347,11 +347,7 @@ the [unit slots](../discussion/idioms/unit-slots.md) discussion for valid choice
 produced by the conversion operation.  (This is usually the same as the input `Rep`, but can differ
 in rare cases, such as integer promotion, or Eigen expression templates.)
 
-!!! warning "Lifetime risk"
-    If the result of this operation is an Eigen expression template, it refers to its operands
-    instead of owning its own copy of the data.  The result is valid only as long as its operands
-    are alive.  If it needs to outlive them, materialize it with [`eval()`](./eigen.md#eval).  See
-    our [Eigen safety guide](../discussion/concepts/eigen_safety.md) to learn more.
+--8<-- "lifetime-risk-maybe-lazy.md"
 
 **With** a template argument, `.as<T>(unit)`, the output `Rep` will be `T`.
 
@@ -379,11 +375,7 @@ slots](../discussion/idioms/unit-slots.md) discussion for valid choices for `uni
 produced by the conversion operation.  (This is usually the same as the input `Rep`, but can differ
 in rare cases, such as integer promotion, or Eigen expression templates.)
 
-!!! warning "Lifetime risk"
-    If the result of this operation is an Eigen expression template, it refers to its operands
-    instead of owning its own copy of the data.  The result is valid only as long as its operands
-    are alive.  If it needs to outlive them, materialize it with [`eval()`](./eigen.md#eval).  See
-    our [Eigen safety guide](../discussion/concepts/eigen_safety.md) to learn more.
+--8<-- "lifetime-risk-maybe-lazy.md"
 
 
 **With** a template argument, `.in<T>(unit)`, the output type will be `T`.

mkdocs.yml

@@ -58,6 +58,11 @@ markdown_extensions:
   - pymdownx.inlinehilite
   - pymdownx.keys
   - pymdownx.smartsymbols
+  # Reusable text snippets, included via `--8<-- "file.md"`.  These live outside of `docs/` because
+  # they are not pages in their own right: they get inlined into the pages that include them.
+  - pymdownx.snippets:
+      base_path: [doc_snippets]
+      check_paths: true
   - pymdownx.superfences:
       custom_fences:
         - name: mermaid