Improve the (PDF) Manual (#989)

* manual: Fix Heading Levels

* manual: Some improvements

* changes: Update changelog

Author: johannes-wolf

.github/workflows/ci.yml

@@ -36,4 +36,5 @@ jobs:
           just install @local
           just install @preview
           just test
+          just manual
           just docs

CHANGES.md

@@ -4,6 +4,8 @@
 - Added a new `content.wrap` style key that takes a function to wrap content in, useful for applying Typst styling, such as text color (#964)
 - Fixed a division by zero bug when shortening paths to zero length (#962)
 - The content element now supports the `wrap:` style to apply a function to they Typst content (e.g. applying text attributes) (#964)
+- The PDF API-Reference is back: manual.pdf (#974)
+- All docstrings are now written in Typst (#974)
 
 # 0.4.2
 - The `tree` element now has a `anchor:` argument to position the tree (#929)

docs/style.typ

@@ -1,3 +1,5 @@
+#import "/src/lib.typ" as cetz
+
 #let colors = (
   "any": rgb("#eff0f3"),
   "content": rgb("#a6ebe6"),
@@ -23,3 +25,146 @@
   box(raw(name), inset: 2pt, baseline: 2pt, radius: 2pt,
     fill: colors.at(name, default: colors.at("any")), stroke: none)
 }
+
+#let show-docstring(comment, level) = {
+  let text = comment.text
+  let arguments = comment.arguments
+  let result = comment.result
+
+  set heading(outlined: false, offset: level)
+
+  block([
+    #eval(text, mode: "markup", scope: (
+      cetz: cetz,
+    ))
+  ])
+
+  if arguments != () {
+    heading("Parameters")
+    list(..arguments.map(arg => {
+      let types = arg.types
+      if types == none { types = ("any",) }
+      block(
+        strong(raw(arg.name)) + [ ]
+        + types.map(show-type).join([ ]) + [\ ]
+        + eval(arg.text, mode: "markup")
+      )
+    }))
+  }
+
+  if result.any(r => r.text != "") {
+    heading("Result")
+
+    let show-result(r) = if r.text != "" {
+      let type = r.type
+      if type == none { type = "any" }
+      block(
+        show-type(type) + [\ ] + eval(r.text, mode: "markup")
+      )
+    }
+
+    if result.len() > 1 {
+      list(..result.map(show-result))
+    } else {
+      show-result(result.first())
+    }
+  }
+}
+
+/// Show a function signature annoted with types from the docstring
+#let show-annotated-signature(signature, comment) = block({
+  set par(leading: 0.35em)
+
+  let name = signature.name
+
+  let arguments = signature.arguments.map(arg => {
+    let comment-arg = comment.arguments.find(comment-arg => {
+      comment-arg.name == arg.name
+    })
+    if comment-arg == none {
+      comment-arg = (types: (), name: name)
+    }
+
+    let types = comment-arg.types
+    if types == none { types = () }
+
+    if arg.has-default {
+      raw(arg.name + ":") + [ ] + types.map(show-type).join([ ])
+    } else {
+      raw(arg.name) + [ ] + types.map(show-type).join([ ])
+    }
+  })
+
+  let result = if comment.result != () {
+    [ #sym.arrow.r ] + comment.result.map(r => show-type(r.type)).join([ or ])
+  } else {
+    []
+  }
+
+  text(blue, raw(name)) + raw("(") + [\ ] + arguments.map(v => h(1em) + v).join([,\ ]) + [\ ] + raw(")") + result
+})
+
+/// Show a single module/file
+#let show-module(docs, name, level: 3) = {
+  for item in docs.at(name) {
+    if item.at("signature", default: none) == none {
+      continue
+    }
+
+    let function-name = item.signature.name
+    if function-name.starts-with("_") {
+      continue
+    }
+
+    [#heading(function-name, level: level) #label(function-name)]
+    show-annotated-signature(item.signature, item.comment)
+    show-docstring(item.comment, level)
+  }
+}
+
+// Root show function for manual.typ
+#let setup(body) = {
+  set heading(numbering: (..nums) => {
+    let nums = nums.pos()
+    if nums.len() <= 2 {
+      return nums.map(n => [#n]).join([.])
+    }
+  }, hanging-indent: 0cm)
+
+  /// Render an example side-by-side with its source code.
+  let render-example(code, vertical: false) = {
+    let columns = if vertical {
+      (1fr,)
+    } else {
+      (1fr, 2fr,)
+    }
+
+    let align = if vertical {
+      (x, y) => (center + top, left + top).at(y)
+    } else {
+      (x, y) => (center + horizon, left + top).at(x)
+    }
+
+    let stroke = 1pt + gray
+    let line = if vertical { table.hline } else { table.vline }
+
+    block(radius: 2pt, stroke: stroke, breakable: false, {
+      table(columns: columns, align: align, stroke: none,
+        cetz.canvas({
+          let preamble = "import cetz.draw: *\n"
+          eval(preamble + code, mode: "code", scope: (
+            cetz: cetz,
+          ))
+        }),
+        line(stroke: (paint: gray, thickness: 1pt, dash: "dashed")),
+        raw(code, lang: "typc"),
+      )
+    })
+  }
+
+  show raw.where(lang: "example"): it => render-example(it.text)
+  show raw.where(lang: "example-vertical"): it => render-example(it.text, vertical: true)
+  show regex("type:([\w-]+)"): it => show-type(it.text.replace("type:", ""))
+
+  body
+}

justfile

@@ -24,6 +24,8 @@ update-test *filter: build
 gallery: build
   for f in "{{gallery_dir}}"/*.typ; do typst c "$f" "${f/typ/png}"; done
 
-docs: build
+manual: build
   typst compile --root . manual.typ
+
+docs: build
   typst query --root . manual.typ "<metadata>" --field value | python ./docs/genhtml.py -o ./docs/_generated

manual.pdf

@@ -1,14 +1,7 @@
-#import "/src/lib.typ" as cetz
-
-#import "/docs/style.typ": show-type
+#import "/docs/style.typ": show-type, show-module, setup, cetz
 #import "/docs/typlodocus/extractor.typ"
 
-#set heading(numbering: (..nums) => {
-  let nums = nums.pos()
-  if nums.len() <= 2 {
-    return nums.map(n => [#n]).join([.])
-  }
-}, hanging-indent: 0cm)
+#show: setup
 
 #let modules = (
   [Canvas],
@@ -28,17 +21,18 @@
   "src/draw/util.typ",
 
   [Libraries], 1,
-  [Angle],
-  "src/lib/angle.typ",
-  [Tree],
-  "src/lib/tree.typ",
-  [Decorations],
-  [Path],
-  "src/lib/decorations/path.typ",
-  [Brace],
-  "src/lib/decorations/brace.typ",
-  [Palette],
-  "src/lib/palette.typ",
+    [Angle],
+    "src/lib/angle.typ",
+    [Tree],
+    "src/lib/tree.typ",
+    [Decorations], 2,
+      [Path],
+      "src/lib/decorations/path.typ",
+      [Brace],
+      "src/lib/decorations/brace.typ",
+    1,
+    [Palette],
+    "src/lib/palette.typ",
   0,
 
   [Internals], 1,
@@ -82,138 +76,7 @@
 // Generate query metadata
 #metadata(docs) <metadata>
 
-/// Show a function signature annoted with types from the docstring
-#let show-annotated-signature(signature, comment) = block({
-  set par(leading: 0.35em)
-
-  let name = signature.name
-
-  let arguments = signature.arguments.map(arg => {
-    let comment-arg = comment.arguments.find(comment-arg => {
-      comment-arg.name == arg.name
-    })
-    if comment-arg == none {
-      comment-arg = (types: (), name: name)
-    }
-
-    let types = comment-arg.types
-    if types == none { types = () }
-
-    if arg.has-default {
-      raw(arg.name + ":") + [ ] + types.map(show-type).join([ ])
-    } else {
-      raw(arg.name) + [ ] + types.map(show-type).join([ ])
-    }
-  })
-
-  let result = if comment.result != () {
-    [ #sym.arrow.r ] + comment.result.map(r => show-type(r.type)).join([ or ])
-  } else {
-    []
-  }
-
-  text(blue, raw(name)) + raw("(") + [\ ] + arguments.map(v => h(1em) + v).join([,\ ]) + [\ ] + raw(")") + result
-})
-
-/// Render an example side-by-side with its source code.
-#let render-example(code, vertical: false) = {
-  let columns = if vertical {
-    (1fr,)
-  } else {
-    (1fr, 2fr,)
-  }
-
-  let align = if vertical {
-    (x, y) => (center + top, left + top).at(y)
-  } else {
-    (x, y) => (center + horizon, left + top).at(x)
-  }
-
-  let stroke = 1pt + gray
-  let line = if vertical { table.hline } else { table.vline }
-
-  block(radius: 2pt, stroke: stroke, {
-    table(columns: columns, align: align, stroke: none,
-      cetz.canvas({
-        let preamble = "import cetz.draw: *\n"
-        eval(preamble + code, mode: "code", scope: (
-          cetz: cetz,
-        ))
-      }),
-      line(stroke: (paint: gray, thickness: 1pt, dash: "dashed")),
-      raw(code, lang: "typc"),
-    )
-  })
-}
-
-#show raw.where(lang: "example"): it => render-example(it.text)
-#show raw.where(lang: "example-vertical"): it => render-example(it.text, vertical: true)
-#show regex("type:([\w-]+)"): it => show-type(it.text.replace("type:", ""))
-
-#let show-docstring(comment, level) = {
-  let text = comment.text
-  let arguments = comment.arguments
-  let result = comment.result
-
-  set heading(outlined: false, offset: level)
-
-  block([
-    #eval(text, mode: "markup", scope: (
-      cetz: cetz,
-    ))
-  ])
-
-  if arguments != () {
-    heading("Parameters")
-    list(..arguments.map(arg => {
-      let types = arg.types
-      if types == none { types = ("any",) }
-      block(
-        strong(raw(arg.name)) + [ ]
-        + types.map(show-type).join([ ]) + [\ ]
-        + eval(arg.text, mode: "markup")
-      )
-    }))
-  }
-
-  if result.any(r => r.text != "") {
-    heading("Result")
-
-    let show-result(r) = if r.text != "" {
-      let type = r.type
-      if type == none { type = "any" }
-      block(
-        show-type(type) + [\ ] + eval(r.text, mode: "markup")
-      )
-    }
-
-    if result.len() > 1 {
-      list(..result.map(show-result))
-    } else {
-      show-result(result.first())
-    }
-  }
-}
-
-/// Show a single module/file
-#let show-module(name, level: 3) = {
-  for item in docs.at(name) {
-    if item.at("signature", default: none) == none {
-      continue
-    }
-
-    let function-name = item.signature.name
-    if function-name.starts-with("_") {
-      continue
-    }
-
-    [#heading(function-name, level: level) #label(function-name)]
-    show-annotated-signature(item.signature, item.comment)
-    show-docstring(item.comment, level)
-  }
-}
-
-
+// Outline
 #columns(2, outline(depth: 4))
 #pagebreak()
 
@@ -244,7 +107,10 @@ From this point on only the code inside the
 canvas block will be shown in examples unless specified otherwise.
 
 ```example
+// Draw a circle
 circle((0, 0))
+
+// Draw a line
 line((1,-1), (2,1))
 ```
 
@@ -297,13 +163,13 @@ stroke and fill styling unless said otherwise.
   How to stroke the border or the path of the draw element. #link("https://typst.app/docs/reference/visualize/line/#parameters-stroke")[See Typst's line documentation for more details.]
 
 = API
+#let heading-offset = 1
 #for item in modules {
-  let heading-offset = 1
   if type(item) == int {
     heading-offset = 1 + item
   } else if type(item) != str {
     heading(item, offset: heading-offset)
   } else {
-    show-module(item, level: 2 + heading-offset)
+    show-module(docs, item, level: 2 + heading-offset)
   }
 }