added manual

docs/config.typ

@@ -0,0 +1,61 @@
+/// Creates a dictionary of all configuration parameters
+///
+/// - default-font-family (str): The default font family
+/// - default font-size (length): The absolute default font size
+/// - italic-font-family (str): The italic font family (for value descriptions)
+/// - italic-font-size (length): The absolute italic font size
+/// - background (color): The diagram background color
+/// - text-color (color): The default color used to display text
+/// - link-color (color): The color used to display links and arrows
+/// - bit-i-color (color): The color used to display bit indices
+/// - border-color (color): The color used to display borders
+/// - bit-width (float): The width of a bit
+/// - bit-height (float): The height of a bit
+/// - description-margin (float): The margin between descriptions
+/// - dash-length (float): The length of individual dashes (for dashed lines)
+/// - dash-space (float): The space between two dashes (for dashed lines)
+/// - arrow-size (float): The size of arrow heads
+/// - margins (tuple[float]): TODO -> remove
+/// - arrow-margin (float): The margin between arrows and the structures they link
+/// - values-gap (float): The gap between individual values
+/// - arrow-label-distance (float): The distance between arrows and their labels
+/// - force-descs-on-side (bool): If true, descriptions are placed on the side of the structure, otherwise, they are placed as close as possible to the bit
+/// - left-labels (bool): If true, descriptions are put on the left, otherwise, they default to the right hand side
+/// - width (float): TODO -> remove
+/// - height (float): TODO -> remove
+/// - full-page (bool): If true, the page will be resized to fit the diagram and take the background color
+/// -> dictionary
+#let config(
+  default-font-family: "Ubuntu Mono",
+  default-font-size: 15pt,
+  italic-font-family: "Ubuntu Mono",
+  italic-font-size: 12pt,
+  background: white,
+  text-color: black,
+  link-color: black,
+  bit-i-color: black,
+  border-color: black,
+  bit-width: 30,
+  bit-height: 30,
+  description-margin: 10,
+  dash-length: 6,
+  dash-space: 4,
+  arrow-size: 10,
+  margins: (20, 20, 20, 20),
+  arrow-margin: 4,
+  values-gap: 5,
+  arrow-label-distance: 5,
+  force-descs-on-side: false,
+  left-labels: false,
+  width: 1200,
+  height: 800,
+  full-page: false
+) = {}
+
+/// Dark theme config
+/// - ..args (any): see #doc-ref("config.config")
+#let dark(..args) = {}
+
+/// Blueprint theme config
+/// - ..args (any): see #doc-ref("config.config")
+#let blueprint(..args) = {}

docs/examples.typ

@@ -0,0 +1,73 @@
+#import "@preview/cetz:0.2.2": draw
+#import "../src/lib.typ": schema
+#import "../src/util.typ"
+
+#let example-preamble = "import \"../src/lib.typ\": *;"
+
+#let example(src, show-src: true, vertical: false, fill: true) = {
+  src = src.text.trim()
+  let full-src = example-preamble + src
+  let body = eval(full-src)
+
+  block(width: 100%,
+    align(center,
+      box(
+        stroke: black + 1pt,
+        radius: .5em,
+        fill: if fill {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,
+            body,
+            if vertical {table.hline()} else {table.vline()}, src-block
+          )
+        } else {
+          table(
+            inset: 1em,
+            body
+          )
+        }
+      )
+    )
+  )
+}
+
+#let config-config = example(raw("
+let ex = schema.load(```yaml
+structures:
+  main:
+    bits: 4
+    ranges:
+      3-0:
+        name: default
+```)
+schema.render(ex, config: config.config())
+"))
+
+#let config-dark = example(raw("
+let ex = schema.load(```yaml
+structures:
+  main:
+    bits: 4
+    ranges:
+      3-0:
+        name: dark
+```)
+schema.render(ex, config: config.dark())
+"))
+
+#let config-blueprint = example(raw("
+let ex = schema.load(```yaml
+structures:
+  main:
+    bits: 4
+    ranges:
+      3-0:
+        name: blueprint
+```)
+schema.render(ex, config: config.blueprint())
+"))

docs/schema.typ

@@ -0,0 +1,14 @@
+/// Loads a schema from a file or a raw block.
+/// This function returns a dictionary of structures
+/// 
+/// Supported formats: #schema.valid-extensions.map(e => raw("." + e)).join(", ")
+/// - path-or-schema (str, raw): If it is a string, defines the path to load. \
+///   If it is a raw block, its content is directly parsed (the block's language will define the format to use)
+/// -> dictionary
+#let load(path-or-schema) = {}
+
+/// Renders the given schema
+/// This functions
+/// - structures (dictionary): A schema dictionary, as returned by #doc-ref("schema.load")
+/// - config (auto, dictionary): The configuration parameters, as returned by #doc-ref("config.config")
+#let render(structures, config: auto)

manual.typ

@@ -0,0 +1,79 @@
+#import "@preview/tidy:0.3.0"
+#import "src/lib.typ"
+#import "src/schema.typ"
+#import "docs/examples.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)[rivet #sym.dash.em v#lib.version])
+
+#let doc-ref(target, full: false, var: false) = {
+  let (module, func) = target.split(".")
+  let label-name = module + func
+  let display-name = func
+  if full {
+    display-name = target
+  }
+  if not var {
+    label-name += "()"
+    display-name += "()"
+  }
+  link(label(label-name))[#display-name]
+}
+
+#show link: set text(blue)
+
+= Introduction
+
+This package provides a way to make beautiful register diagrams using the CeTZ package. It can be used to document Assembly instructions or binary registers
+
+This is a port of the #link("https://git.kb28.ch/HEL/rivet")[homonymous Python script] for Typst. For more information on the schema format, please check out the original project's #link("https://git.kb28.ch/HEL/rivet/src/branch/main/format.md")[format.md]
+
+= Usage
+
+Simply import `schema` from #link("src/lib.typ") and call `schema.load` to parse a schema description. Then use `schema.render` to render it, et voilà !
+#pad(left: 1em)[```typ
+#import "src/lib.typ": schema
+#let doc = schema.load("path/to/schema.typ")
+#schema.render(doc)
+```]
+
+= Config presets
+
+Aside from the default config, some example presets are also provided:
+- #doc-ref("config.config", full: true): the default theme, black on white
+  #examples.config-config
+- #doc-ref("config.dark", full: true): a dark theme, with white text and lines on a black background
+  #examples.config-dark
+- #doc-ref("config.blueprint", full: true): a blueprint theme, with white text and lines on a blue background
+  #examples.config-blueprint
+
+#pagebreak(weak: true)
+
+= Reference
+
+#let doc-config = tidy.parse-module(
+  read("docs/config.typ"),
+  name: "config",
+  scope: (
+    doc-ref: doc-ref
+  )
+)
+#tidy.show-module(doc-config, sort-functions: false)
+
+#pagebreak()
+
+#let doc-schema = tidy.parse-module(
+  read("docs/schema.typ"),
+  name: "schema",
+  scope: (
+    schema: schema,
+    doc-ref: doc-ref
+  )
+)
+#tidy.show-module(doc-schema, sort-functions: false)