improve documentation

docs/function-types.typ

@@ -0,0 +1,49 @@
+#let theorem-kind = (link-to: 0, numbering: 0)
+
+/// TODO
+///
+/// - name (content, str): The name of the #ref-type("theorem").
+/// - link-to (label, selector, selector-function, none): Link the #ref-type("theorem")
+///     to some other content. For #ref-type("label")s and #ref-type("selector")s the last
+///     match before the #ref-type("theorem") is used.
+/// - numbering (theorem-numbering-function, none): See #ref-type("theorem-numbering-function")
+///    for more information. Can be set to #ref-type("none") for unnumbered #ref-type("theorem")s.
+/// - body (content):
+/// -> theorem
+#let theorem-function(name: none, link-to: theorem-kind.link-to, numbering: theorem-kind.numbering, body) = 0
+
+/// Create combined numberings from `theorem` and the content linked to it.
+///
+/// There are two pre-defined #ref-type("theorem-numbering-function")s: @@numbering-concat() and @@numbering-proof().
+///
+/// - thm (theorem): The `theorem` for which the numbering should be generated.
+///     See also @@get-theorem-parameters(). 
+/// - referenced (bool): This is false if
+///     the numbering was requested from the `theorem` it belongs to.
+///     Otherwise it is false. See @@numbering-proof() as an example.
+/// -> content
+#let theorem-numbering-function(thm, referenced) = 0
+
+/// Defines how the #ref-type("theorem") will look. Use @@get-theorem-parameters() to get
+/// all information stored in the #ref-type("theorem").
+///
+/// There are two pre-defined #ref-type("style-function")s: @@style-simple() and @@style-reversed().
+///
+/// - thm (theorem):
+/// -> content
+#let style-function(thm) = 0
+
+/// Useful for more advanced queries. See @@last-heading() for an example.
+///
+/// - loc (location): When used in `link-to` parameter
+///     of some #ref-type("theorem") its #ref-type("location")
+///     will be passed when resolving the link with @@resolve-link().
+/// -> content, none
+#let selector-function(loc) = 0
+
+/// A normal numbering function as described
+/// in the #show-link("https://typst.app/docs/reference/meta/numbering/#parameters-numbering")[typst documentation].
+///
+/// - ..state (int):
+/// -> content
+#let numbering-function(..state) = 0

docs/generate_readme.py

@@ -57,13 +57,15 @@ def convert_to_markdown(content):
         elif element["func"] == "text":
             result += element["text"] + "\n"
         elif element["func"] == "raw":
-            result += "```" + element["lang"] + "\n" + element["text"] + "\n" + "```\n\n"
-        elif element["func"] == "metadata":
+            result += "```" + element["lang"] + "\n" + element["text"] + "\n" + "```\n"
+        elif element["func"] == "metadata" and "code" in element["value"]:
             with open(file_name(), mode="w") as file:
                 file.write(element["value"]["code"])
             compile_file()
             result += f"\n![image]({image_name()})\n"
             GENERATED_IMAGE_COUNT += 1
+        elif element["func"] == "metadata" and "text" in element["value"]:
+            result += element["value"]["text"] + "\n"
         elif element["func"] == "enum":
             element = element["children"][0]
             result += str(element["number"]) + ". " + element["body"]["text"] + "\n"

docs/readme.typ

@@ -36,6 +36,10 @@
   return (scope, code)
 }
 
+#let export-only(text) = [
+  #metadata((text: text)) <export>
+]
+
 #show enum: it => [#it <export>]
 
 = Lemmify <export>
@@ -47,6 +51,8 @@ This means that the interface might change with updates to typst <export>
 (for example if user-defined element functions are introduced). <export>
 But no functionality should be lost. <export>
 
+#export-only("\nIf you are encountering any bugs, have questions or are missing features, feel free to open an issue on [GitHub](\"https://github.com/Marmare314/lemmify\").")
+
 == Basic usage <export>
 
 1. Import the Lemmify library
@@ -73,10 +79,16 @@ But no functionality should be lost. <export>
 ```
 #step3 <export>
 
-4. Customize the styling using show rules. For example, to add a red box around proofs
+4. Customize the styling using show rules. For example, to add a block around proofs
 
 #let step4 = ```typst
-#show select-kind(proof): box.with(stroke: red + 1pt, inset: 1em)
+#show select-kind(proof): block.with(
+  breakable: true,
+  width: 100%,
+  fill: gray,
+  inset: 1em,
+  radius: 5pt
+)
 ```
 #step4 <export>
 
@@ -87,6 +99,10 @@ But no functionality should be lost. <export>
   Theorem content goes here.
 ]<thm>
 
+#theorem(numbering: none)[
+  Another theorem.
+]
+
 #proof(link-to: <thm>)[
   Complicated proof.
 ]<proof>
@@ -103,6 +119,12 @@ The result should now look something like this <export>
   export-setup: "#set page(width: 300pt, height: auto, margin: 10pt)"
 )
 
+The default-theorems function has one more parameter max-reset-level <export>
+which controls on which headings the group counters are reset. <export>
+By default they will be reset on every heading. <export>
+To customize the look and behaviour of the theorems there <export>
+are some more parameters available. <export>
+
 == Examples <export>
 
 This example shows how corollaries can be numbered after the last theorem. <export>
@@ -183,8 +205,3 @@ This example shows how corollaries can be numbered after the last theorem. <expo
 )
 
 #include "source_docs.typ"
-
-// If you are encountering any bugs, have questions or <export>
-// are missing features, feel free to open an issue on <export>
-// #link("https://github.com/Marmare314/lemmify")[GitHub] <export>
-// . <export>

docs/source_docs.typ

@@ -1,41 +1,130 @@
-#import "@preview/tidy:0.1.0": parse-module, show-module
-
-#let lib-parsed = parse-module(read("../src/lib.typ"))
-#let reset-counter-parsed = parse-module(read("../src/reset-counter.typ"))
-#let selectors-parsed = parse-module(read("../src/selectors.typ"))
-#let styles-parsed = parse-module(read("../src/styles.typ"))
-#let numbered-parsed = parse-module(read("../src/numbered.typ"))
-#let theorem-parsed = parse-module(read("../src/theorem.typ"))
+#import "@preview/tidy:0.1.0": parse-module, show-module, styles
+
+#let custom-type-colors = (
+  "theorem-function": rgb("#f9dfff"),
+  "theorem-numbering-function": rgb("#f9dfff"),
+  "numbering-function": rgb("#f9dfff"),
+  "style-function": rgb("#f9dfff"),
+  "selector-function": rgb("#f9dfff"),
+  "theorem": rgb("#fff173"),
+  "numbered": rgb("#bfb3ff")
+)
+
+#let type-colors = (
+  "content": rgb("#a6ebe6"),
+  "color": rgb("#a6ebe6"),
+  "str": rgb("#d1ffe2"),
+  "none": rgb("#ffcbc4"),
+  "auto": rgb("#ffcbc4"),
+  "bool": rgb("#ffedc1"),
+  "int": rgb("#e7d9ff"),
+  "float": rgb("#e7d9ff"),
+  "ratio": rgb("#e7d9ff"),
+  "length": rgb("#e7d9ff"),
+  "angle": rgb("#e7d9ff"),
+  "relative-length": rgb("#e7d9ff"),
+  "fraction": rgb("#e7d9ff"),
+  "symbol": rgb("#eff0f3"),
+  "array": rgb("#eff0f3"),
+  "dictionary": rgb("#eff0f3"),
+  "arguments": rgb("#eff0f3"),
+  "selector": rgb("#eff0f3"),
+  "module": rgb("#eff0f3"),
+  "stroke": rgb("#eff0f3"),
+  "function": rgb("#f9dfff"),
+  ..custom-type-colors
+)
+
+#let get-type-color(type) = type-colors.at(type, default: rgb("#eff0f3"))
+
+#let link-color = blue.darken(50%)
+
+#let ref-type(type, text-color: link-color) = {
+  if type in custom-type-colors {
+    link(label(type + "()"), text(text-color, raw(type)))
+  } else {
+    text(text-color, raw(type))
+  }
+}
+
+#let show-link(url, txt) = {
+  link(url)[#text(link-color, txt)]
+}
+
+#let show-type(type) = { 
+  h(2pt)
+  box(outset: 2pt, fill: get-type-color(type), radius: 2pt, ref-type(type, text-color: black))
+  h(2pt)
+}
+
+#let style = (
+  show-type: show-type,
+  show-outline: styles.default.show-outline,
+  show-function: styles.default.show-function,
+  show-parameter-list: styles.default.show-parameter-list,
+  show-parameter-block: styles.default.show-parameter-block
+)
+
+#let parse-module-params = (
+  scope: (
+    ref-type: ref-type,
+    show-link: show-link
+  )
+)
+
+#let show-module-params = (
+  style: style,
+  show-module-name: false,
+  show-outline: false,
+  sort-functions: none,
+)
+
+#let lib-parsed = parse-module(read("../src/lib.typ"), ..parse-module-params)
+#let reset-counter-parsed = parse-module(read("../src/reset-counter.typ"), ..parse-module-params)
+#let selectors-parsed = parse-module(read("../src/selectors.typ"), ..parse-module-params)
+#let styles-parsed = parse-module(read("../src/styles.typ"), ..parse-module-params)
+#let numbered-parsed = parse-module(read("../src/numbered.typ"), ..parse-module-params)
+#let theorem-parsed = parse-module(read("../src/theorem.typ"), ..parse-module-params)
+#let function-types-parsed = parse-module(read("function-types.typ"), ..parse-module-params)
 
 = Documentation
 
-#show-module(lib-parsed)
+#show-module(lib-parsed, ..show-module-params)
 
-== Styles
+== Function types
 
-There are a few pre-defined `style-function`s and `theorem-numbering-function`s.
+#show-module(function-types-parsed, ..show-module-params)
 
-#show-module(styles-parsed)
+== theorem
+#label("theorem()")
 
-== Selectors
+A #ref-type("theorem") is a #ref-type("figure") with some additional
+information stored in one of its parameters.
 
-The selectors can be used in show-rules to
-customize the `theorem`s styling as well as
-with the `link-to` parameter.
+#show-module(theorem-parsed, ..show-module-params)
 
-#show-module(selectors-parsed)
+== numbered
+#label("numbered()")
 
-== Resetting counters
+A #ref-type("numbered") is a #ref-type("heading"), #ref-type("page"),
+#ref-type("math.equation") or #ref-type("figure") that is already embedded
+in the document (that means it was obtained by a query). The `numbering`
+also has to be different from #ref-type("none").
 
-#show-module(reset-counter-parsed)
+#show-module(numbered-parsed, ..show-module-params)
 
-== Theorem utilities
+== Styles
 
-The functions in the remaining two sections are only needed when defining custom style or
-theorem-numbering-functions.
+#show-module(styles-parsed, ..show-module-params)
 
-#show-module(theorem-parsed)
+== Selectors
+
+The selectors can be used in show-rules to
+customize the #ref-type("theorem")s styling as well as
+with the `link-to` parameter.
+
+#show-module(selectors-parsed, ..show-module-params)
 
-== Numbered utilities
+== Resetting counters
 
-#show-module(numbered-parsed)
+#show-module(reset-counter-parsed, ..show-module-params)

src/lib.typ

@@ -8,26 +8,23 @@
 #let LEMMIFY-DEFAULT-THEOREM-GROUP = "LEMMIFY-DEFAULT-THEOREM-GROUP"
 #let LEMMIFY-DEFAULT-PROOF-GROUP = "LEMMIFY-DEFAULT-PROOF-GROUP"
 
-/// Create a new theorem function. The style is only visible
-/// once the `theorem-rules` have been applied.
-/// The generated functions will be referred to as `kind-function`s
-/// and the `figures` created by it will be referred to as `theorem`s.
+/// Creates a new #ref-type("theorem-function").
 ///
-/// - kind-name (str): The name of the theorem kind. It acts
-///                    as an identifier together with `group` when using `select-kind`,
-///                    so it should be unique.
+/// - kind-name (str): The name of the theorem kind. It also acts
+///     as an identifier together with `group` when using `select-kind`,
+///     so it should be unique.
 /// - group (str): The group identifier. Each theorem group shares one counter.
-/// - link-to (label, selector, selector-function, none): Link the `theorem` to some
-///                             other content. See `numbering-concat` for how this is used. For `label`s and `selector`s the last one before the `theorem` is used. `selector-function`s are functions `(location) -> content` which can be used for
-///                              more advanced queries.
-/// - numbering (theorem-numbering-function): A function `(theorem, bool) -> content`.
-///                                           The `bool` argument is true only if
-///                                           the numbering is requested from a reference
-///                                           instead of from the theorem itself (see numbering-proof).
+/// - link-to (label, selector, selector-function, none): This parameter sets
+///     what the #ref-type("theorem")s created by the #ref-type("theorem-function") will be linked to
+///     by default.
+/// - numbering (theorem-numbering-function, none): Specify a default value for
+///     the `numbering` parameter of the #ref-type("theorem-function").
 /// - subnumbering (numbering-function, str, none): The subnumbering is
-///                                   needed to convert the theorems counter to content,
-///                                   which is then used in the `theorem-numbering-function`.
-/// - style (style-function): A function `(thm) -> content` which is used to style the theorem.
+///     needed to convert the #ref-type("theorem")s counter to content,
+///     which is then used in the #ref-type("theorem-numbering-function").
+/// - style (style-function): Specifies how the #ref-type("theorem")s will look. This will only be
+///     visible once the @@theorem-rules() have been applied.
+/// -> theorem-function
 #let theorem-kind(
   kind-name,
   group: LEMMIFY-DEFAULT-THEOREM-GROUP,
@@ -39,7 +36,7 @@
   assert-type(kind-name, "kind-name", str)
   assert-type(group, "group", str)
   assert-type(link-to, "link-to", label, selector, function, None)
-  assert-type(numbering, "numbering", function)
+  assert-type(numbering, "numbering", function, None)
   assert-type(subnumbering, "subnumbering", function, str, None)
   assert-type(style, "style", function)
 
@@ -60,7 +57,7 @@
   )
 }
 
-/// Apply the style of every `theorem` and handle references to `theorem`s.
+/// Apply the style of every #ref-type("theorem") and handle references to #ref-type("theorem")s.
 ///
 /// - content (content):
 /// -> content
@@ -91,17 +88,21 @@
 
 /// Generate a few common theorem kinds in the specified language.
 ///
-/// This function accepts all parameters of `theorem-kind` once for proofs and
+/// Returns a dictionary of the form
+/// `(theorem, lemma, corollary, remark, proposition, example, definition, proof, theorem-rules)`.
+/// The `theorem-rules` can be applied using a show statement. If `max-reset-level` is `none`
+/// it will be the same as @@theorem-rules().
+///
+/// This function accepts all parameters of @@theorem-kind() once for proofs and
 /// once for all kinds except for proofs.
-/// So for information on the missing parameters refer to `theorem-kind`.
 ///
 /// - group (str):
 /// - proof-group (str):
 /// - lang (str): The language in which the theorem kinds are generated.
 /// - style (style-function):
 /// - proof-style (style-function):
-/// - numbering (theorem-numbering-function):
-/// - proof-numbering (theorem-numbering-function):
+/// - numbering (theorem-numbering-function, none):
+/// - proof-numbering (theorem-numbering-function, none):
 /// - link-to (label, selector, selector-function, none):
 /// - proof-link-to (label, selector, selector-function, none):
 /// - subnumbering (numbering-function, str, none):
@@ -128,8 +129,8 @@
   assert-type(lang, "lang", str)
   assert-type(style, "style", function)
   assert-type(proof-style, "proof-style", function)
-  assert-type(numbering, "numbering", function)
-  assert-type(proof-numbering, "proof-numbering", function)
+  assert-type(numbering, "numbering", function, None)
+  assert-type(proof-numbering, "proof-numbering", function, None)
   assert-type(link-to, "link-to", label, selector, function, None)
   assert-type(proof-link-to, "proof-link-to", label, selector, function, None)
   assert-type(subnumbering, "subnumbering", function, str, None)