book: document blocks

Author: Kijewski

book/src/creating_templates.md

@@ -92,6 +92,36 @@ recognized:
   struct HelloTemplate<'a> { ... }
   ```
 
+* `blocks` (e.g. `blocks = ["title", "content"]`):
+  automatically generates (a number of) sub-templates that act as if they had a
+  `block = "..."` attribute. You can access the sub-templates with the method
+  <code>my_template.as_<em>block_name</em>()</code>, where *`block_name`* is the
+  name of the block:
+  ```rust,ignore
+  #[derive(Template)]
+  #[template(
+      ext = "txt",
+      source = "
+          {% block title %} ... {% endblock %}
+          {% block content %} ... {% endblock %}
+      ",
+      blocks = ["title", "content"]
+  )]
+  struct News<'a> {
+      title: &'a str,
+      message: &'a str,
+  }
+
+  let news = News {
+      title: "Announcing Rust 1.84.1",
+      message: "The Rust team has published a new point release of Rust, 1.84.1.",
+  };
+  assert_eq!(
+      news.as_title().render().unwrap(),
+      "<h1>Announcing Rust 1.84.1</h1>"
+  );
+  ```
+
 * `escape` (e.g. `escape = "none"`): override the template's extension used for
   the purpose of determining the escaper for this template. See the section
   on configuring custom escapers for more information.

book/src/features.md

@@ -74,12 +74,20 @@ The most useful catch-all feature for a quick start might be `"full"`,
 which enables all implemented features, i.e.:
 
 ```toml
-full = ["default", "code-in-doc", "serde_json"]
+full = ["default", "blocks", "code-in-doc", "serde_json"]
 ```
 
 In production or once your project is “maturing” you might want to manually opt-in to any needed
 features with a finer granularity instead of depending on `"full"`.
 
+### `"blocks"`
+
+<blockquote class="right" style="padding:0.5ex 1ex; margin:0 0 1ex 1ex; font-size:80%">
+enabled by <code>"full"</code>
+</blockquote>
+
+Enables using [the template attribute `blocks`](creating_templates.html#the-template-attribute).
+
 ### `"serde_json"`
 
 <blockquote class="right" style="padding:0.5ex 1ex; margin:0 0 1ex 1ex; font-size:80%">

rinja_derive/src/lib.rs

@@ -100,6 +100,56 @@ use rustc_hash::FxBuildHasher;
 /// the generated code (`code`) or `all` for both.
 /// The requested data will be printed to stdout at compile time.
 ///
+/// ### block
+///
+/// E.g. `block = "block_name"`
+///
+/// Renders the block by itself.
+/// Expressions outside of the block are not required by the struct, and
+/// inheritance is also supported. This can be useful when you need to
+/// decompose your template for partial rendering, without needing to
+/// extract the partial into a separate template or macro.
+///
+/// ```rust,ignore
+/// #[derive(Template)]
+/// #[template(path = "hello.html", block = "hello")]
+/// struct HelloTemplate<'a> { ... }
+/// ```
+///
+/// ### blocks
+///
+/// E.g. `blocks = ["title", "content"]`
+///
+/// Automatically generates (a number of) sub-templates that act as if they had a
+/// `block = "..."` attribute. You can access the sub-templates with the method
+/// <code>my_template.as_<em>block_name</em>()</code>, where *`block_name`* is the
+/// name of the block:
+///
+/// ```rust,ignore
+/// #[derive(Template)]
+/// #[template(
+///     ext = "txt",
+///     source = "
+///         {% block title %} ... {% endblock %}
+///         {% block content %} ... {% endblock %}
+///     ",
+///     blocks = ["title", "content"]
+/// )]
+/// struct News<'a> {
+///     title: &'a str,
+///     message: &'a str,
+/// }
+///
+/// let news = News {
+///     title: "Announcing Rust 1.84.1",
+///     message: "The Rust team has published a new point release of Rust, 1.84.1.",
+/// };
+/// assert_eq!(
+///     news.as_title().render().unwrap(),
+///     "<h1>Announcing Rust 1.84.1</h1>"
+/// );
+/// ```
+///
 /// ### escape
 ///
 /// E.g. `escape = "none"`