improved doc + moved examples to separate file

doc/example.typ

@@ -0,0 +1,41 @@
+#import "@preview/cetz:0.2.2": draw
+#import "../src/circuit.typ": circuit
+#import "../src/util.typ"
+
+#let example-preamble = "import \"../src/lib.typ\": *;"
+#let example-scope = (
+  draw: draw
+)
+
+#let example(src, show-src: true, vertical: false, fill: true) = {
+  src = src.text
+  let full-src = example-preamble + src
+  let body = eval(full-src, scope: example-scope)
+  let img = circuit(length: 2em, body)
+
+  block(width: 100%,
+    align(center,
+      box(
+        stroke: black + 1pt,
+        radius: .5em,
+        fill: if fill {util.colors.yellow.lighten(80%)} else {none},
+        if show-src {
+          let src-block = align(left, raw(src, lang: "typc"))
+          table(
+            columns: if vertical {1} else {2},
+            inset: 1em,
+            align: horizon + center,
+            stroke: none,
+            img,
+            if vertical {table.hline()} else {table.vline()}, src-block
+          )
+        } else {
+          table(
+            inset: 1em,
+            img
+          )
+        }
+      )
+    )
+  )
+}

doc/examples.typ

@@ -0,0 +1,76 @@
+#import "example.typ": example
+
+#let alu = example(```
+element.alu(x: 0, y: 0, w: 1, h: 2, id: "alu")
+wire.stub("alu-port-in1", "west")
+wire.stub("alu-port-in2", "west")
+wire.stub("alu-port-out", "east")
+```)
+
+#let block = example(```
+element.block(
+  x: 0, y: 0, w: 2, h: 2, id: "block",
+  ports: (
+    north: ((id: "clk", clock: true),),
+    west: ((id: "in1", name: "A"),
+           (id: "in2", name: "B")),
+    east: ((id: "out", name: "C"),)
+  )
+)
+wire.stub("block-port-clk", "north")
+wire.stub("block-port-in1", "west")
+wire.stub("block-port-in2", "west")
+wire.stub("block-port-out", "east")
+```)
+
+#let extender = example(```
+element.extender(
+  x: 0, y: 0, w: 3, h: 1,
+  id: "extender"
+)
+wire.stub("extender-port-in", "west")
+wire.stub("extender-port-out", "east")
+```)
+
+#let multiplexer = example(```
+element.multiplexer(
+  x: 0, y: 0, w: 1, h: 3,
+  id: "multiplexer",
+  entries: 3
+)
+wire.stub("multiplexer.north", "north")
+wire.stub("multiplexer-port-out", "east")
+
+element.multiplexer(
+  x: 0, y: -4, w: 1, h: 3,
+  id: "multiplexer2",
+  entries: ("A", "B", "C")
+)
+wire.stub("multiplexer2.south", "south")
+wire.stub("multiplexer2-port-out", "east")
+
+for i in range(3) {
+  wire.stub("multiplexer-port-in" + str(i), "west")
+  wire.stub("multiplexer2-port-in" + str(i), "west")
+}
+```)
+
+#let wires = example(```
+for i in range(3) {
+  draw.circle((i * 3, 0), radius: .1, name: "p" + str(i * 2))
+  draw.circle((i * 3 + 2, 1), radius: .1, name: "p" + str(i * 2 + 1))
+  draw.content((i * 3 + 1, -1), raw(wire.wire-styles.at(i)))
+}
+wire.wire("w1", ("p0", "p1"), style: "direct")
+wire.wire("w2", ("p2", "p3"), style: "zigzag")
+wire.wire("w3", ("p4", "p5"), style: "dodge",
+          dodge-y: -0.5, dodge-margins: (0.5, 0.5))
+```, vertical: true)
+
+#let stub = example(```
+draw.circle((0, 0), radius: .1, name: "p")
+wire.stub("p", "north", name: "north", length: 1)
+wire.stub("p", "east", name: "east", vertical: true)
+wire.stub("p", "south", name: "south", length: 15pt)
+wire.stub("p", "west", name: "west", length: 3em)
+```)

manual.typ

@@ -1,9 +1,66 @@
 #import "@preview/tidy:0.3.0"
-#import "@preview/cetz:0.2.2": draw
+#import "@preview/cetz:0.2.2": draw, canvas
+#import "src/lib.typ"
+#import "doc/examples.typ"
 #import "src/circuit.typ": circuit
+#import "src/element.typ"
 #import "src/util.typ"
 #import "src/wire.typ"
 
+#set heading(numbering: (..num) => if num.pos().len() < 4 {
+  numbering("1.1", ..num)
+})
+#{
+  outline(indent: true, depth: 3)
+}
+#set page(numbering: "1/1", header: align(right)[circuiteria #sym.dash.em v#lib.version])
+#show link: set text(blue)
+#show heading.where(level: 3): it => context {
+  let cnt = counter(heading)
+  let i = cnt.get().at(it.depth) - 1
+  let color = util.colors.values().at(i)
+  block(width: 100%)[
+    #grid(
+      columns: (auto, 1fr),
+      column-gutter: 1em,
+      align: horizon,
+      it,
+      {
+        place(horizon)[
+          #line(
+            start: (0%, 0%),
+            end: (100%, 0%),
+            stroke: color + 1pt
+          )
+        ]
+        place(horizon)[
+          #circle(radius: 3pt, stroke: none, fill: color)
+        ]
+        place(horizon+right)[
+          #circle(radius: 3pt, stroke: none, fill: color)
+        ]
+      }
+    )
+  ]
+}
+
+= Introduction
+
+This package provides a way to make beautiful block circuit diagrams using the CeTZ package.
+
+= Usage
+
+Simply import #link("src/lib.typ") and call the `circuit` function:
+#pad(left: 1em)[```typ
+#import "src/lib.typ"
+#lib.circuit({
+  import lib: *
+  ...
+})
+```]
+
+= Reference
+
 #let circuit-docs = tidy.parse-module(
   read("src/circuit.typ"),
   name: "circuit",
@@ -11,18 +68,53 @@
 )
 #tidy.show-module(circuit-docs)
 
+#pagebreak()
+
 #let util-docs = tidy.parse-module(
   read("src/util.typ"),
   name: "util",
   require-all-parameters: true,
-  scope: (util: util)
+  scope: (
+    util: util,
+    canvas: canvas,
+    draw: draw
+  )
 )
 #tidy.show-module(util-docs)
 
+#pagebreak()
+
 #let wire-docs = tidy.parse-module(
   read("src/wire.typ"),
   name: "wire",
   require-all-parameters: true,
-  scope: (wire: wire, circuit: circuit, draw: draw)
+  scope: (
+    wire: wire,
+    circuit: circuit,
+    draw: draw,
+    examples: examples
+  )
 )
 #tidy.show-module(wire-docs)
+
+#pagebreak()
+
+#let element-docs = tidy.parse-module(
+  read("src/elements/element.typ") + "\n" +
+  read("src/elements/alu.typ") + "\n" +
+  read("src/elements/block.typ") + "\n" +
+  read("src/elements/extender.typ") + "\n" +
+  read("src/elements/multiplexer.typ"),
+  name: "element",
+  require-all-parameters: true,
+  scope: (
+    element: element,
+    circuit: circuit,
+    draw: draw,
+    wire: wire,
+    tidy: tidy,
+    examples: examples
+  )
+)
+
+#tidy.show-module(element-docs, sort-functions: false)

src/circuit.typ

@@ -3,6 +3,8 @@
 
 /// Draws a block circuit diagram
 ///
+/// This function is also available at the package root
+///
 /// - body (none, array, element): A code block in which draw functions have been called
 /// - length (length, ratio): Optional base unit
 /// -> none

src/elements/alu.typ

@@ -37,6 +37,19 @@
   return (f, tl, tr, br, bl)
 }
 
+/// Draws an ALU with two inputs
+///
+/// #examples.alu
+/// - x (number, dictionary): see `elmt()`
+/// - y (number, dictionary): see `elmt()`
+/// - w (number): see `elmt()`
+/// - h (number): see `elmt()`
+/// - name (none, str): see `elmt()`
+/// - name-anchor (str): see `elmt()`
+/// - fill (none, color): see `elmt()`
+/// - stroke (stroke): see `elmt()`
+/// - id (str): see `elmt()`
+/// - debug (dictionary): see `elmt()`
 #let alu(
   x: none,
   y: none,
@@ -48,7 +61,6 @@
   stroke: black + 1pt,
   id: "",
   debug: (
-    grid: false,
     ports: false
   )
 ) = {

src/elements/block.typ

@@ -13,6 +13,21 @@
   return (f, tl, tr, br, bl)
 }
 
+/// Draws a block element
+///
+/// #examples.block
+/// - x (number, dictionary): see `elmt()`
+/// - y (number, dictionary): see `elmt()`
+/// - w (number): see `elmt()`
+/// - h (number): see `elmt()`
+/// - name (none, str): see `elmt()`
+/// - name-anchor (str): see `elmt()`
+/// - ports (dictionary): see `elmt()`
+/// - ports-margins (dictionary): see `elmt()`
+/// - fill (none, color): see `elmt()`
+/// - stroke (stroke): see `elmt()`
+/// - id (str): see `elmt()`
+/// - debug (dictionary): see `elmt()`
 #let block(
   x: none,
   y: none,
@@ -26,7 +41,6 @@
   stroke: black + 1pt,
   id: "",
   debug: (
-    grid: false,
     ports: false
   )
 ) = element.elmt(

src/elements/element.typ

@@ -16,6 +16,33 @@
   return ({}, tl, tr, br, bl)
 }
 
+/// Draws an element
+/// - draw-shape (function): Draw function
+/// - x (number, dictionary): The x position (bottom-left corner).
+///
+///   If it is a dictionary, it should be in the format `(rel: number, to: str)`, where `rel` is the offset and `to` the base anchor
+/// - y (number, dictionary): The y position (bottom-left corner).
+///
+///   If it is a dictionary, it should be in the format `(from: str, to: str)`, where `from` is the base anchor and `to` is the id of the port to align with the anchor
+/// - w (number): Width of the element
+/// - h (number): Height of the element
+/// - name (none, str): Optional name of the block
+/// - name-anchor (str): Anchor for the optional name
+/// - ports (dictionary): Dictionary of ports. The keys are cardinal directions ("north", "east", "south" and/or "west"). The values are arrays of ports (dictionaries) with the following fields:
+///   - `id` (`str`): (Required) Port id
+///   - `name` (`str`): Optional name displayed *in* the block
+///   - `clock` (`bool`): Whether it is a clock port (triangle symbol)
+///   - `vertical` (`bool`): Whether the name should be drawn vertically
+/// - ports-margins (dictionary): Dictionary of ports margins (used with automatic port placement). They keys are cardinal directions ("north", "east", "south", "west"). The values are tuples of (<start>, <end>) margins (numbers)
+/// - fill (none, color): Fill color
+/// - stroke (stroke): Border stroke
+/// - id (str): The block id (for future reference)
+/// - auto-ports (bool): Whether to use auto port placements or not. If false, `draw-shape` is responsible for adding the appropiate ports
+/// - ports-y (array): Array of the ports y offsets (used with `auto-ports: false`)
+/// - debug (dictionary): Dictionary of debug options.
+///
+///   Supported fields include:
+///     - `ports`: if true, shows dots on all ports of the element
 #let elmt(
   draw-shape: default-draw-shape,
   x: none,
@@ -32,7 +59,6 @@
   auto-ports: true,
   ports-y: (),
   debug: (
-    grid: false,
     ports: false
   )
 ) = draw.get-ctx(ctx => {

src/elements/extender.typ

@@ -25,6 +25,19 @@
   return (f, tl, tr, br, bl)
 }
 
+/// Draws a bit extender
+///
+/// #examples.extender
+/// - x (number, dictionary): see `elmt()`
+/// - y (number, dictionary): see `elmt()`
+/// - w (number): see `elmt()`
+/// - h (number): see `elmt()`
+/// - name (none, str): see `elmt()`
+/// - name-anchor (str): see `elmt()`
+/// - fill (none, color): see `elmt()`
+/// - stroke (stroke): see `elmt()`
+/// - id (str): see `elmt()`
+/// - debug (dictionary): see `elmt()`
 #let extender(
   x: none,
   y: none,
@@ -36,7 +49,6 @@
   stroke: black + 1pt,
   id: "",
   debug: (
-    grid: false,
     ports: false
   )
 ) = {

src/elements/multiplexer.typ

@@ -21,6 +21,20 @@
   return (f, tl, tr, br, bl)
 }
 
+/// Draws a multiplexer
+///
+/// #examples.multiplexer
+/// - x (number, dictionary): see `elmt()`
+/// - y (number, dictionary): see `elmt()`
+/// - w (number): see `elmt()`
+/// - h (number): see `elmt()`
+/// - name (none, str): see `elmt()`
+/// - name-anchor (str): see `elmt()`
+/// - entries (int, array): If it is an integer, it defines the number of input ports (automatically named with their binary index). If it is an array of string, it defines the name of each input.
+/// - fill (none, color): see `elmt()`
+/// - stroke (stroke): see `elmt()`
+/// - id (str): see `elmt()`
+/// - debug (dictionary): see `elmt()`
 #let multiplexer(
   x: none,
   y: none,
@@ -33,7 +47,6 @@
   stroke: black + 1pt,
   id: "",
   debug: (
-    grid: false,
     ports: false
   )
 ) = {
@@ -45,6 +58,10 @@
       let bits = util.lpad(str(i, base: 2), nbits)
       ports.push((id: "in" + str(i), name: bits))
     }
+  } else {
+    for (i, port) in entries.enumerate() {
+      ports.push((id: "in" + str(i), name: port))
+    }
   }
   
   element.elmt(

src/util.typ

@@ -1,4 +1,15 @@
 /// Predefined color palette
+/// #let w = 5
+/// #box(width: 100%, align(center)[
+///   #canvas(length: 2em, {
+///     for (i, color) in util.colors.pairs().enumerate() {
+///       let x = calc.rem(i, w) * 2
+///       let y = calc.floor(i / w) * 2
+///       draw.rect((x, -y), (x + 1, -y - 1), fill: color.last(), stroke: none)
+///       draw.content((x + 0.5, -y - 1.25), color.first())
+///     }
+///   })
+/// ])
 #let colors = (
   orange: rgb(245, 180, 147),
   yellow: rgb(250, 225, 127),
@@ -11,11 +22,11 @@
 ///
 /// #example(`#util.lpad("0100", 8)`, mode: "markup")
 ///
-/// - s (str): The string to pad
+/// - string (str): The string to pad
 /// - len (int): The target length
 /// -> str
-#let lpad(s, len) = {
+#let lpad(string, len) = {
-  let res = "0" * len + s
+  let res = "0" * len + string
   return res.slice(-len)
 }
 

src/wire.typ

@@ -2,22 +2,7 @@
 #import "util.typ": opposite-anchor
 
 /// List of valid wire styles
-/// #box(width: 100%, align(center)[
+/// #examples.wires
-///   #circuit({
-///     draw.circle((0, 0), radius: .1, name: "p1")
-///     draw.circle((2, 1), radius: .1, name: "p2")
-///     draw.circle((3, 0), radius: .1, name: "p3")
-///     draw.circle((5, 1), radius: .1, name: "p4")
-///     draw.circle((6, 0), radius: .1, name: "p5")
-///     draw.circle((8, 1), radius: .1, name: "p6")
-///     wire.wire("w1", ("p1", "p2"), style: "direct")
-///     wire.wire("w2", ("p3", "p4"), style: "zigzag")
-///     wire.wire("w3", ("p5", "p6"), style: "dodge", dodge-y: -0.5, dodge-margins: (0.5, 0.5))
-///     draw.content((1, -1), [`direct`])
-///     draw.content((4, -1), [`zigzag`])
-///     draw.content((7, -1), [`dodge`])
-///   })
-/// ])
 #let wire-styles = ("direct", "zigzag", "dodge")
 #let signal-width = 1pt
 #let bus-width = 1.5pt
@@ -118,7 +103,7 @@
 /// - style (str): The wire's style (see `wire-styles` for possible values)
 /// - reverse (bool): If true, the start and end points will be swapped (useful in cases where the start point depends on the end point, for example with perpendiculars)
 /// - zigzag-ratio (ratio): Position of the zigzag vertical relative to the horizontal span (only with style "zigzag")
-/// - dodge-y (int, float, length, ratio): Y position to dodge the wire to (only with style "dodge")
+/// - dodge-y (number): Y position to dodge the wire to (only with style "dodge")
 /// - dodge-sides (array): The start and end sides (going out of the connected element) of the wire (only with style "dodge")
 /// - dodge-margins (array): The start and end margins (i.e. space before dodging) of the wire (only with style "dodge")
 #let wire(
@@ -233,13 +218,7 @@
 
 /// Draws a wire stub (useful for unlinked ports)
 ///
-/// #box(width: 100%, align(center)[
+/// #examples.stub
-///   #circuit({
-///     draw.circle((0, 0), radius: .1, name: "p")
-///     wire.stub("p", "east", name: "port")
-///   })
-/// ])
-///
 /// - port-id (str): The port anchor
 /// - side (str): The side on which the port is (one of "north", "east", "south", "west")
 /// - name (none, str): Optional name displayed at the end of the stub