Test documentation examples in CI (lambda-fairy#257)

Closes lambda-fairy#230

Closes lambda-fairy#256

.github/workflows/ci.yml

@@ -26,22 +26,26 @@ jobs:
         override: true
         components: clippy
 
+    # Do *not* use `--all-features` here, as the optional dependencies take a
+    # long time to build, and will be tested in the "examples" job anyway
     - name: Run tests
       run: cargo test --workspace --all-targets
 
     - name: Check Clippy
       run: cargo clippy --workspace --all-targets -- -D warnings
 
-  # Optional features (i.e. web framework integrations) take a long time to
-  # build and rarely break. Speed up CI by checking them separately.
-  all-features:
-    name: All features
+  # Please keep this in sync with `publish-docs.yml`
+  documentation:
+    name: Documentation
     runs-on: ubuntu-latest
 
     steps:
 
     - name: Check out repository
       uses: actions/checkout@v2
+      with:
+        # Documentation build uses `git describe` which requires history
+        fetch-depth: 0
 
     - name: Install Rust
       uses: actions-rs/toolchain@v1
@@ -50,21 +54,17 @@ jobs:
         profile: minimal
         override: true
 
-    - name: Check build
-      run: cargo check --workspace --all-features --all-targets
+    - name: Build documentation
+      run: cd docs && make -j$(nproc)
 
-  # Please keep this in sync with `publish-docs.yml`
-  documentation:
-    name: Documentation
+  examples:
+    name: Examples
     runs-on: ubuntu-latest
 
     steps:
 
     - name: Check out repository
       uses: actions/checkout@v2
-      with:
-        # Documentation build uses `git describe` which requires history
-        fetch-depth: 0
 
     - name: Install Rust
       uses: actions-rs/toolchain@v1
@@ -73,8 +73,8 @@ jobs:
         profile: minimal
         override: true
 
-    - name: Build documentation
-      run: cd docs && make -j$(nproc)
+    - name: Doctest
+      run: cd doctest && cargo test
 
   rustfmt:
     name: Rustfmt

.gitignore

@@ -1,3 +1,5 @@
 target
 /Cargo.lock
 docs/site
+doctest/Cargo.lock
+doctest/lib.rs

Cargo.toml

@@ -6,4 +6,5 @@ members = [
 ]
 exclude = [
     "docs",
+    "doctest",
 ]

docs/content/control-structures.md

@@ -12,6 +12,7 @@ enum Princess { Celestia, Luna, Cadance, TwilightSparkle }
 
 let user = Princess::Celestia;
 
+# let _ = maud::
 html! {
     @if user == Princess::Luna {
         h1 { "Super secret woona to-do list" }
@@ -26,12 +27,14 @@ html! {
         p { "Nothing to see here; move along." }
     }
 }
+# ;
 ```
 
 `@if let` is supported as well:
 
 ```rust
 let user = Some("Pinkie Pie");
+# let _ = maud::
 html! {
     p {
         "Hello, "
@@ -43,6 +46,7 @@ html! {
         "!"
     }
 }
+# ;
 ```
 
 ## Looping with `@for`
@@ -51,6 +55,7 @@ Use `@for .. in ..` to loop over the elements of an iterator.
 
 ```rust
 let names = ["Applejack", "Rarity", "Fluttershy"];
+# let _ = maud::
 html! {
     p { "My favorite ponies are:" }
     ol {
@@ -59,6 +64,7 @@ html! {
         }
     }
 }
+# ;
 ```
 
 ## Declaring variables with `@let`
@@ -67,6 +73,7 @@ Declare a new variable within a template using `@let`. This can be useful when w
 
 ```rust
 let names = ["Applejack", "Rarity", "Fluttershy"];
+# let _ = maud::
 html! {
     @for name in &names {
         @let first_letter = name.chars().next().unwrap();
@@ -79,6 +86,7 @@ html! {
         }
     }
 }
+# ;
 ```
 
 ## Matching with `@match`
@@ -90,6 +98,7 @@ enum Princess { Celestia, Luna, Cadance, TwilightSparkle }
 
 let user = Princess::Celestia;
 
+# let _ = maud::
 html! {
     @match user {
         Princess::Luna => {
@@ -106,4 +115,5 @@ html! {
         _ => p { "Nothing to see here; move along." }
     }
 }
+# ;
 ```

docs/content/elements-attributes.md

@@ -5,13 +5,15 @@
 Write an element using curly braces:
 
 ```rust
+# let _ = maud::
 html! {
     h1 { "Poem" }
     p {
         strong { "Rock," }
         " you are a rock."
     }
 }
+# ;
 ```
 
 Before version 0.18, Maud allowed the curly braces to be omitted. This syntax was [removed][#137] and now causes an error instead.
@@ -23,6 +25,7 @@ Before version 0.18, Maud allowed the curly braces to be omitted. This syntax wa
 Terminate a void element using a semicolon:
 
 ```rust
+# let _ = maud::
 html! {
     link rel="stylesheet" href="poetry.css";
     p {
@@ -35,6 +38,7 @@ html! {
         "Rock."
     }
 }
+# ;
 ```
 
 The result will be rendered with HTML syntax – `<br>` not `<br />`.
@@ -48,12 +52,14 @@ Maud also supports ending a void element with a slash: `br /`. This syntax is [d
 Maud also supports elements and attributes with hyphens in them. This includes [custom elements], [data attributes], and [ARIA annotations].
 
 ```rust
+# let _ = maud::
 html! {
     article data-index="12345" {
         h1 { "My blog" }
         tag-cloud { "pinkie pie pony cute" }
     }
 }
+# ;
 ```
 
 [custom elements]: https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements
@@ -65,6 +71,7 @@ html! {
 Add attributes using the syntax: `attr="value"`. You can attach any number of attributes to an element. The values must be quoted: they are parsed as string literals.
 
 ```rust
+# let _ = maud::
 html! {
     ul {
         li {
@@ -79,20 +86,23 @@ html! {
         }
     }
 }
+# ;
 ```
 
 ## Empty attributes: `checked`
 
 Declare an empty attribute by omitting the value.
 
 ```rust
+# let _ = maud::
 html! {
     form {
         input type="checkbox" name="cupcakes" checked;
         " "
         label for="cupcakes" { "Do you like cupcakes?" }
     }
 }
+# ;
 ```
 
 Before version 0.22.2, Maud required a `?` suffix on empty attributes: `checked?`. This is no longer necessary ([#238]), but still supported for backward compatibility.
@@ -104,28 +114,34 @@ Before version 0.22.2, Maud required a `?` suffix on empty attributes: `checked?
 Add classes and IDs to an element using `.foo` and `#bar` syntax. You can chain multiple classes and IDs together, and mix and match them with other attributes:
 
 ```rust
+# let _ = maud::
 html! {
     input#cannon.big.scary.bright-red type="button" value="Launch Party Cannon";
 }
+# ;
 ```
 
 The classes and IDs can be quoted. This is useful for names with numbers or symbols which otherwise wouldn't parse:
 
 ```rust
+# let _ = maud::
 html! {
     div."col-sm-2" { "Bootstrap column!" }
 }
+# ;
 ```
 
 ## Implicit `div` elements
 
 If the element name is omitted, but there is a class or ID, then it is assumed to be a `div`.
 
 ```rust
+# let _ = maud::
 html! {
     #main {
         "Main content!"
         .tip { "Storing food in a refrigerator can make it 20% cooler." }
     }
 }
+# ;
 ```

docs/content/getting-started.md

@@ -37,7 +37,7 @@ fn main() {
 
 Run this program with `cargo run`, and you should get the following:
 
-```
+```html
 <p>Hi, Lyra!</p>
 ```
 

docs/content/index.md

@@ -3,6 +3,7 @@
 # A macro for writing HTML
 
 ```rust
+# let _ = maud::
 html! {
     h1 { "Hello, world!" }
     p.intro {
@@ -11,6 +12,7 @@ html! {
         " template language."
     }
 }
+# ;
 ```
 
 Maud is an HTML [template engine] for Rust. It's implemented as a macro, `html!`, which compiles your markup to specialized Rust code. This unique approach makes Maud templates blazing fast, super type-safe, and easy to deploy.

docs/content/partials.md

@@ -44,6 +44,8 @@ Using the `page` function will return the markup for the whole page.
 Here's an example:
 
 ```rust
+# use maud::{html, Markup};
+# fn page(title: &str, greeting_box: Markup) -> Markup { greeting_box }
 page("Hello!", html! {
     div { "Greetings, Maud." }
 });

docs/content/render-trait.md

@@ -11,7 +11,7 @@ Below are some examples of using `Render`. Feel free to use these snippets in yo
 When writing a web page, it can be annoying to write `link rel="stylesheet"` over and over again. This example provides a shorthand for linking to CSS stylesheets.
 
 ```rust
-use maud::{Markup, Render};
+use maud::{html, Markup, Render};
 
 /// Links to a CSS stylesheet at the given path.
 struct Css(&'static str);
@@ -32,8 +32,9 @@ When debugging an application, it can be useful to see its internal state. But t
 To avoid extra allocation, we override the `.render_to()` method instead of `.render()`. This doesn't do any escaping by default, so we wrap the output in an `Escaper` as well.
 
 ```rust
-use maud::{Render, Escaper};
+use maud::{Escaper, html, Render};
 use std::fmt;
+use std::fmt::Write as _;
 
 /// Renders the given value using its `Debug` implementation.
 struct Debug<T: fmt::Debug>(T);
@@ -53,9 +54,7 @@ impl<T: fmt::Debug> Render for Debug<T> {
 We also use the [`ammonia`][ammonia] library, which sanitizes the resulting markup.
 
 ```rust
-extern crate ammonia;
-extern crate pulldown_cmark;
-
+use ammonia;
 use maud::{Markup, PreEscaped, Render};
 use pulldown_cmark::{Parser, html};