Greatly simplify logic for creating example images

Author: ntjess

README.md

@@ -29,12 +29,11 @@ The easiest method is to import `wrap-it: wrap-content` from the
 ## Vanilla
 
 ``` typst
-#set par(justify: true)
 #let fig = figure(
-  rect(fill: teal, radius: 0.5em, width: 8em),
-  caption: [A figure],
+rect(fill: teal, radius: 0.5em, width: 8em),
+caption: [A figure],
 )
-#let body = lorem(40)
+#let body = lorem(30)
 #wrap-content(fig, body)
 ```
 ![Example 1](https://www.github.com/ntjess/wrap-it/raw/v0.1.1/assets/example-1.png)
@@ -43,10 +42,10 @@ The easiest method is to import `wrap-it: wrap-content` from the
 
 ``` typst
 #wrap-content(
-  fig,
-  body,
-  align: bottom + right,
-  column-gutter: 2em
+fig,
+body,
+align: bottom + right,
+column-gutter: 2em
 )
 ```
 ![Example 2](https://www.github.com/ntjess/wrap-it/raw/v0.1.1/assets/example-2.png)
@@ -57,20 +56,47 @@ The easiest way to get a uniform, highly-customizable margin is through
 boxing your image:
 
 ``` typst
-#let boxed = box(fig, inset: 0.5em)
+#let boxed = box(fig, inset: 0.25em)
 #wrap-content(boxed)[
-  #lorem(40)
+#lorem(30)
 ]
 ```
 ![Example 3](https://www.github.com/ntjess/wrap-it/raw/v0.1.1/assets/example-3.png)
 
 ## Wrapping two images in the same paragraph
 
+Note that for longer captions (as is the case in the bottom figure
+below), providing an explicit `columns` parameter is necessary to inform
+caption text of where to wrap.
+
 ``` typst
 #let fig2 = figure(
-  rect(fill: lime, radius: 0.5em),
-  caption: [Another figure],
+rect(fill: lime, radius: 0.5em),
+caption: [#lorem(10)],
+)
+#wrap-top-bottom(
+bottom-kwargs: (columns: (1fr, 2fr)),
+box(fig, inset: 0.25em),
+fig2,
+lorem(50),
 )
-#wrap-top-bottom(boxed, fig2, lorem(62))
 ```
-![Example 4](https://www.github.com/ntjess/wrap-it/raw/v0.1.1/assets/example-4.png)
+![Example 4](https://www.github.com/ntjess/wrap-it/raw/v0.1.1/assets/example-4.png)
+
+## Adding a label to a wrapped figure
+
+Typst can only append labels to figures in content mode. So, when
+wrapping text around a figure that needs a label, you must first place
+your figure in a content block with its label, then wrap it:
+
+``` typst
+#show ref: it => underline(text(blue, it))
+#let fig = [
+  #figure(
+    rect(fill: red, radius: 0.5em, width: 8em),
+    caption:[Labeled]
+  )<fig:lbl>
+]
+#wrap-content(fig, [Fortunately, @fig:lbl's label can be referenced within the wrapped text. #lorem(15)])
+```
+![Example 5](https://www.github.com/ntjess/wrap-it/raw/v0.1.1/assets/example-5.png)

assets/example-1.png

@@ -0,0 +1,28 @@
+#import "readme.typ": eval-kwargs, showman-config
+#import "@preview/showman:0.1.2": runner
+#show raw.where(lang: "example"): it => it
+
+
+#let get-example-blocks(body) = {
+  let example-blocks = ()
+  let example-blocks-regex = regex("```example\n([\s\S]+?)\n```")
+  for match in body.matches(example-blocks-regex) {
+    example-blocks.push(match.captures.at(0))
+  }
+  example-blocks
+}
+
+#let all-blocks = get-example-blocks(read("readme.typ"))
+#set page(margin: 1em, ..showman-config.page-size)
+// Dummy first page to match showman expectations
+#pagebreak()
+#for (ii, example) in all-blocks.enumerate() {
+  eval(
+    mode: "markup",
+    "#let output(body) = body;\n" + eval-kwargs.eval-prefix + example,
+  )
+  if ii != all-blocks.len() - 1 {
+    pagebreak()
+  }
+}
+

assets/example-2.png

@@ -4,6 +4,14 @@
 #let eval-kwargs = (
   eval-prefix: "
       #import \"@preview/wrap-it:0.1.1\"
+
+      #set par(justify: true)
+      #let fig = figure(
+        rect(fill: teal, radius: 0.5em, width: 8em),
+        caption: [A figure],
+      )
+      #let body = lorem(30)
+
       #let wrap-content(..args) = output(wrap-it.wrap-content(..args))
       #let wrap-top-bottom(..args) = output(wrap-it.wrap-top-bottom(..args))
     ",
@@ -23,7 +31,6 @@
   underline(it)
 }
 #set page(height: auto)
-
 = Wrap-It: Wrapping text around figures & content
 Until https://github.com/typst/typst/issues/553 is resolved, `typst` doesn't natively support wrapping text around figures or other content. However, you can use `wrap-it` to mimic much of this functionality:
 - Wrapping images left or right of their text
@@ -41,8 +48,7 @@ The easiest method is to import `wrap-it: wrap-content` from the `@preview` pack
 = Sample use:
 == Vanilla
 
-```globalexample
-#set par(justify: true)
+```example
 #let fig = figure(
 rect(fill: teal, radius: 0.5em, width: 8em),
 caption: [A figure],
@@ -52,7 +58,7 @@ caption: [A figure],
 ```
 
 == Changing alignment and margin
-```globalexample
+```example
 #wrap-content(
 fig,
 body,
@@ -63,31 +69,37 @@ column-gutter: 2em
 
 == Uniform margin around the image
 The easiest way to get a uniform, highly-customizable margin is through boxing your image:
-```globalexample
-#let boxed = box(fig, inset: 0.5em)
+```example
+#let boxed = box(fig, inset: 0.25em)
 #wrap-content(boxed)[
 #lorem(30)
 ]
 ```
 == Wrapping two images in the same paragraph
 Note that for longer captions (as is the case in the bottom figure below), providing an explicit `columns` parameter is necessary to inform caption text of where to wrap.
-```globalexample
+```example
 #let fig2 = figure(
 rect(fill: lime, radius: 0.5em),
 caption: [#lorem(10)],
 )
-#wrap-top-bottom(bottom-kwargs: (columns: (1fr, 2fr)), boxed, fig2, lorem(50))
+#wrap-top-bottom(
+bottom-kwargs: (columns: (1fr, 2fr)),
+box(fig, inset: 0.25em),
+fig2,
+lorem(50),
+)
 ```
 
 == Adding a label to a wrapped figure
 Typst can only append labels to figures in content mode. So, when wrapping text around a figure that needs a label, you must first place your figure in a content block with its label, then wrap it:
+
 ```example
 #show ref: it => underline(text(blue, it))
 #let fig = [
   #figure(
     rect(fill: red, radius: 0.5em, width: 8em),
     caption:[Labeled]
-  )<figure-1>
+  )<fig:lbl>
 ]
-#wrap-content(fig, [Fortunately, @figure-1's label can be referenced within the wrapped text. #lorem(15)])
-```
+#wrap-content(fig, [Fortunately, @fig:lbl's label can be referenced within the wrapped text. #lorem(15)])
+```

assets/example-3.png

@@ -1,21 +1,38 @@
 #! /usr/bin/env python3
-from pathlib import Path
-import subprocess
 import re
+from pathlib import Path
+
+from showman.converter import Converter
 
 toml_text = Path("typst.toml").read_text()
 groups = re.match(r".*version = \"(.*?)\"", toml_text, re.DOTALL)
 assert groups
 version = groups.group(1)
 
-cmd = f"""
-showman md \
-    docs/readme.typ \
-    --output README.md \
-    --root_dir . \
-    --assets_dir assets \
-    --git_url https://www.github.com/ntjess/wrap-it/v{version}/ \
-    # --log_level DEBUG
-"""
-print(" ".join(cmd.split()))
-subprocess.run(cmd, check=True, shell=True)
+
+class WrapItConverter(Converter):
+    def _setup_build_folder(self, persist=False):
+        return (
+            self.typst_file.parent,
+            self.typst_file.parent / "make-example-images.typ",
+        )
+
+    def _get_runnable_langs(self):
+        return ["example"]
+
+    def __del__(self):
+        # No need to clean up build directory
+        pass
+
+
+WrapItConverter(
+    "docs/readme.typ",
+    assets_dir="assets",
+    root_dir=".",
+    showable_labels=["example"],
+    # log_level="DEBUG",
+).save(
+    out_path="README.md",
+    remote_url=f"https://www.github.com/ntjess/wrap-it/v{version}/",
+    force=True,
+)