Merge remote-tracking branch 'upstream/master' into violin-plot

doc/example.typ

@@ -0,0 +1,76 @@
+#import "/src/cetz.typ" as cetz
+#import "/src/lib.typ" as cetz-plot
+
+// String that gets prefixed to every example code
+// for compilation only!
+#let example-preamble = "import cetz.draw: *; import cetz-plot: *;"
+#let example-scope = (cetz: cetz, cetz-plot: cetz-plot)
+
+
+/// Render an example from a string
+/// - source (string, raw): Example source code
+/// - args (arguments): Arguments passed down to the canvas
+/// - vertical (boolean): If true, show the code below the canvas
+#let example(source, ..args, vertical: false) = {
+  if type(source) == content {
+    source = source.text
+  }
+
+  let radius = .25cm
+  let border = 1pt + gray
+  let canvas-background = yellow.lighten(95%)
+
+  let picture = cetz.canvas(
+    eval(
+      example-preamble + source,
+      scope: example-scope
+    ),
+    ..args
+  )
+  let source = box(
+    raw(
+      source,
+      lang: "typc"
+    ),
+    width: 100%
+  )
+
+  block(
+    if vertical {
+      align(
+        center,
+        stack(
+          dir: ttb,
+          spacing: 1em,
+          block(
+            width: 100%,
+            clip: true,
+            radius: radius,
+            stroke: border,
+            table(
+              columns: 1,
+              stroke: none,
+              fill: (c,r) => (canvas-background, white).at(r),
+              picture,
+              align(left, source)
+            )
+          ),
+        )
+      )
+    } else {
+      block(
+        table(
+          columns: 2,
+          stroke: none,
+          fill: (canvas-background, white),
+          align: (center + horizon, left),
+          picture,
+          source
+        ),
+        width: 100%,
+        radius: radius,
+        clip: true,
+        stroke: border
+      )
+  }, breakable: false)
+}

doc/style.typ

@@ -0,0 +1,107 @@
+#import "example.typ": example
+#import "/src/lib.typ"
+
+#import "@preview/tidy:0.1.0"
+#import "@preview/t4t:0.3.2": is
+
+#let show-function(fn, style-args) = {
+  [
+    #heading(fn.name, level: style-args.first-heading-level + 1)
+    #label(style-args.label-prefix + fn.name + "()")
+  ]
+  let description = if is.sequence(fn.description) {
+    fn.description.children
+  } else {
+    (fn.description,)
+  }
+  let parameter-index = description.position(e => {
+    e.func() == heading and e.body == [parameters]
+  })
+
+  description = description.map(e => if e.func() == heading {
+    let fields = e.fields()
+    let label = fields.remove("label", default: none)
+    heading(offset: style-args.first-heading-level + 1, fields.remove("body"), ..fields); [#label]
+  } else { e })
+
+  if parameter-index != none {
+    description.slice(0, parameter-index).join()
+  } else {
+    description.join()
+  }
+
+  set heading(level: style-args.first-heading-level + 2)
+
+  block(breakable: style-args.break-param-descriptions, {
+    heading("Parameters", level: style-args.first-heading-level + 2)
+    (style-args.style.show-parameter-list)(fn, style-args.style.show-type)
+  })
+
+  for (name, info) in fn.args {
+    let types = info.at("types", default: ())
+    let description = info.at("description", default: "")
+    if description == [] and style-args.omit-empty-param-descriptions { continue }
+    (style-args.style.show-parameter-block)(
+      name, types, description, 
+      style-args,
+      show-default: "default" in info, 
+      default: info.at("default", default: none),
+    )
+  }
+
+  if parameter-index != none {
+    description.slice(parameter-index+1).join()
+  }
+}
+
+#let show-parameter-block(name, types, content, show-default: true, default: none, in-tidy: false, ..a) = {
+  if type(types) != array {
+    types = (types,)
+  }
+  stack(dir: ttb, spacing: 1em,
+    // name <type>     Default: <default>
+    block(breakable: false, width: 100%, stack(dir: ltr,
+      [#text(weight: "bold", name + [:]) #types.map(tidy.styles.default.show-type).join(" or ")],
+      if show-default {
+        align(right)[
+          Default: #raw(
+            lang: "typc",
+            // Tidy gives defaults as strings but outside of tidy we pass defaults as the actual values
+            if in-tidy { default } else { repr(default) }
+          )
+        ]
+      }
+      )),
+    // text
+    block(inset: (left: .4cm), content)
+  )
+}
+
+
+#let show-type = tidy.styles.default.show-type
+#let show-outline = tidy.styles.default.show-outline
+#let show-parameter-list = tidy.styles.default.show-parameter-list
+
+#let style = (
+  show-function: show-function,
+  show-parameter-block: show-parameter-block.with(in-tidy: true),
+  show-type: show-type,
+  show-outline: show-outline,
+  show-parameter-list: show-parameter-list
+)
+
+#let parse-show-module(path) = {
+  tidy.show-module(
+    tidy.parse-module(
+      read(path),
+      scope: (
+        example: example,
+        show-parameter-block: show-parameter-block,
+        cetz: lib
+      )
+    ),
+    show-outline: false,
+    sort-functions: none,
+    style: style
+  )
+}

doc/util.typ

@@ -0,0 +1,62 @@
+#import "/src/lib.typ" as cetz-plot
+
+/// Make the title-page
+#let make-title() = {
+  let left-fringe = 39%
+  let left-color = rgb(140,90,255).darken(30%)
+  let right-color = white
+
+  let url = "https://github.com/cetz-package/cetz-plot"
+  let authors = (
+    ([Johannes Wolf], "https://github.com/johannes-wolf"),
+    ([fenjalien],     "https://github.com/fenjalien"),
+  )
+
+  set page(
+    numbering: none,
+    background: place(
+      top + left,
+      rect(
+        width: left-fringe,
+        height: 100%,
+        fill: left-color
+      )
+    ),
+    margin: (
+      left: left-fringe * 22cm,
+      top: 12% * 29cm
+    ),
+    header: none,
+    footer: none
+  )
+
+  set text(weight: "bold", left-color)
+  show link: set text(left-color)
+
+  block(
+    place(
+      top + left,
+      dx: -left-fringe * 22cm + 5mm,
+      text(3cm, right-color)[CeTZ]
+    ) +
+    text(3cm)[Plot]
+  )
+  block(
+    v(1cm) +
+    text(
+      20pt,
+      authors.map(v => link(v.at(1), [#v.at(0)])).join("\n")
+    )
+  )
+  block(
+    v(2cm) +
+    text(
+      20pt,
+      link(
+        url,
+        [Version ] + [#cetz-plot.version]
+      )
+    )
+  )
+  pagebreak(weak: true)
+}

gallery/line.typ

@@ -1,26 +1,39 @@
-#import "@preview/cetz:0.2.2": canvas
+#import "@preview/cetz:0.2.2": canvas, draw
 #import "@preview/cetz-plot:0.1.0": plot
 
 #set page(width: auto, height: auto, margin: .5cm)
 
 #let style = (stroke: black, fill: rgb(0, 0, 200, 75))
 
-#canvas(length: 1cm, {
-  plot.plot(size: (8, 6),
-    x-tick-step: none,
-    x-ticks: ((-calc.pi, $-pi$), (0, $0$), (calc.pi, $pi$)),
-    y-tick-step: 1,
+#let f1(x) = calc.sin(x)
+#let fn = (
+  ($ x - x^3"/"3! $, x => x - calc.pow(x, 3)/6),
+  ($ x - x^3"/"3! - x^5"/"5! $, x => x - calc.pow(x, 3)/6 + calc.pow(x, 5)/120),
+  ($ x - x^3"/"3! - x^5"/"5! - x^7"/"7! $, x => x - calc.pow(x, 3)/6 + calc.pow(x, 5)/120 - calc.pow(x, 7)/5040),
+)
+
+#set text(size: 10pt)
+
+#canvas({
+  import draw: *
+
+  // Set-up a thin axis style
+  set-style(axes: (stroke: .5pt, tick: (stroke: .5pt)),
+            legend: (stroke: none, orientation: ttb, item: (spacing: .3), scale: 80%))
+
+  plot.plot(size: (12, 8),
+    x-tick-step: calc.pi/2,
+    x-format: plot.formats.multiple-of,
+    y-tick-step: 2, y-min: -2.5, y-max: 2.5,
+    legend: "inner-north",
     {
-      plot.add(
-        style: style,
-        domain: (-calc.pi, calc.pi), calc.sin)
-      plot.add(
-        hypograph: true,
-        style: style,
-        domain: (-calc.pi, calc.pi), calc.cos)
-      plot.add(
-        hypograph: true,
-        style: style,
-        domain: (-calc.pi, calc.pi), x => calc.cos(x + calc.pi))
+      let domain = (-1.1 * calc.pi, +1.1 * calc.pi)
+
+      for ((title, f)) in fn {
+        plot.add-fill-between(f, f1, domain: domain,
+          style: (stroke: none), label: title)
+      }
+      plot.add(f1, domain: domain, label: $ sin x  $,
+        style: (stroke: black))
     })
 })

justfile

@@ -19,4 +19,4 @@ manual:
   typst c manual.typ manual.pdf
 
 gallery:
-  for f in "{{gallery_dir}}"/*.typ; do typst c "$f" "${f/typ/png}"; done
+  for f in "{{gallery_dir}}"/*.typ; do typst c --root . "$f" "${f/typ/png}"; done

manual.typ

@@ -1 +1,66 @@
-TODO
+#import "/doc/util.typ": *
+#import "/doc/example.typ": example
+#import "/doc/style.typ" as doc-style
+#import "/src/lib.typ": *
+#import "/src/cetz.typ": *
+#import "@preview/tidy:0.2.0"
+
+
+// Usage:
+//   ```example
+//   /* canvas drawing code */
+//   ```
+#show raw.where(lang: "example"): example
+#show raw.where(lang: "example-vertical"): example.with(vertical: true)
+
+#make-title()
+
+#set terms(indent: 1em)
+#set par(justify: true)
+#set heading(numbering: (..num) => if num.pos().len() < 4 {
+    numbering("1.1", ..num)
+  })
+#show link: set text(blue)
+
+// Outline
+#{
+  show heading: none
+  columns(2, outline(indent: true, depth: 3))
+  pagebreak(weak: true)
+}
+
+#set page(numbering: "1/1", header: align(right)[CeTZ-Plot])
+
+= Introduction
+
+CeTZ-Plot is a simple plotting library for use with CeTZ.
+
+= Usage
+
+This is the minimal starting point:
+#pad(left: 1em)[```typ
+#import "@preview/cetz:0.2.2"
+#import "@preview/cetz-plot:0.1.0"
+#cetz.canvas({
+  import cetz.draw: *
+  import cetz-plot: *
+  ...
+})
+```]
+Note that plot functions are imported inside the scope of the `canvas` block.
+All following example code is expected to be inside a `canvas` block, with the `plot`
+module imported into the namespace.
+
+= Plot
+
+#doc-style.parse-show-module("/src/plot.typ")
+#for m in ("line", "bar", "boxwhisker", "contour", "errorbar", "annotation", "formats") {
+  doc-style.parse-show-module("/src/plot/" + m + ".typ")
+}
+
+= Chart
+
+#doc-style.parse-show-module("/src/chart.typ")
+#for m in ("barchart", "boxwhisker", "columnchart", "piechart") {
+  doc-style.parse-show-module("/src/chart/" + m + ".typ")
+}