Skip to content

Commit

Permalink
add source documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
Marmare314 committed Sep 28, 2023
1 parent ce3bc6c commit bd0be91
Show file tree
Hide file tree
Showing 14 changed files with 239 additions and 58 deletions.
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,9 @@ As another example we will number corollarys after the last theorem.


![image](docs/images/image_1.png)

## Custom style example

This examples shows how custom style functions can be defined.
```typst
#import "@preview/lemmify:0.2.0": default-theorems, get-theorem-parameters
Expand Down
18 changes: 18 additions & 0 deletions docs/generate_pdf.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
import os
import subprocess

README_FILE_PATH = os.path.join("docs", "readme.typ")

def main():
print("Compiling " + README_FILE_PATH, end="", flush=True)
completed_process = subprocess.run(["typst", "compile", README_FILE_PATH, "--root", "."], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
if completed_process.returncode != 0:
print(" ✗")
print(completed_process.stderr)
print(completed_process.stdout)
exit(1)
else:
print(" ✓")

if __name__ == "__main__":
main()
Binary file modified docs/readme.pdf
Binary file not shown.
4 changes: 4 additions & 0 deletions docs/readme.typ
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,8 @@ As another example we will number corollarys after the last theorem. <export>
export-setup: "#set page(width: 300pt, height: auto, margin: 10pt)"
)
== Custom style example <export>
This examples shows how custom style functions can be defined. <export>
#let example2 = ```typst
Expand Down Expand Up @@ -182,6 +184,8 @@ This examples shows how custom style functions can be defined. <export>
export-setup: "#set page(width: 500pt, height: auto, margin: 10pt)"
)
#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>
Expand Down
41 changes: 41 additions & 0 deletions docs/source_docs.typ
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
#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"))

= Documentation

#show-module(lib-parsed)

== Styles

There are a few pre-defined `style-function`s and `theorem-numbering-function`s.

#show-module(styles-parsed)

== Selectors

The selectors can be used in show-rules to
customize the `theorem`s styling as well as
with the `link-to` parameter.

#show-module(selectors-parsed)

== Resetting counters

#show-module(reset-counter-parsed)

== Theorem utilities

The functions in the remaining two sections are only needed when defining custom style or
theorem-numbering-functions.

#show-module(theorem-parsed)

== Numbered utilities

#show-module(numbered-parsed)
16 changes: 5 additions & 11 deletions src/export-lib.typ
Original file line number Diff line number Diff line change
Expand Up @@ -45,25 +45,19 @@
}

#let is-theorem
#let assert-theorem
#let get-theorem-parameters
#let resolve-link
#{
import "theorem.typ"
is-theorem = theorem.is-theorem
assert-theorem = theorem.assert-theorem
get-theorem-parameters = theorem.get-theorem-parameters
resolve-link = theorem.resolve-link
}

#let is-countable
#let assert-countable
#let get-countable-parameters
#let display-countable
#let is-numbered
#let display-numbered
#{
import "countable.typ"
is-countable = countable.is-countable
assert-countable = countable.assert-countable
get-countable-parameters = countable.get-countable-parameters
display-countable = countable.display-countable
import "numbered.typ"
is-numbered = numbered.is-numbered
display-numbered = numbered.display-numbered
}
45 changes: 45 additions & 0 deletions src/lib.typ
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,26 @@
#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.
///
/// - 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.
/// - 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).
/// - 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.
#let theorem-kind(
kind-name,
group: LEMMIFY-DEFAULT-THEOREM-GROUP,
Expand Down Expand Up @@ -41,6 +61,10 @@
}

// TODO: handle custom supplements
/// Apply the style of every `theorem` and handle references to `theorem`s.
///
/// - content (content):
/// -> content
#let theorem-rules(content) = {
show figure: it => if is-theorem(it) {
let params = get-theorem-parameters(it)
Expand All @@ -66,6 +90,27 @@
content
}

/// Generate a few common theorem kinds in the specified language.
///
/// 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):
/// - link-to (label, selector, selector-function, none):
/// - proof-link-to (label, selector, selector-function, none):
/// - subnumbering (numbering-function, str, none):
/// - max-reset-level (int, none): If it is not none the theorem counter will
/// be reset on headings below `max-reset-level`.
/// And if `link-to` is set to `last-heading`
/// higher levels will not be displayed in the numbering.
/// -> dictionary
#let default-theorems(
group: LEMMIFY-DEFAULT-THEOREM-GROUP,
proof-group: LEMMIFY-DEFAULT-PROOF-GROUP,
Expand Down
39 changes: 25 additions & 14 deletions src/countable.typ → src/numbered.typ
Original file line number Diff line number Diff line change
@@ -1,22 +1,21 @@
#import "theorem.typ": is-theorem, get-theorem-parameters

// TODO: improve error messages
#let is-countable(c) = {
return (
type(c) == content
and c.func() in (heading, page, math.equation, figure)
)
}

#let assert-countable(c) = {
#let assert-countable(arg, arg-name) = {
assert(
is-countable(c),
message: "expected heading, page, math.equation or figure, got " + type(c)
is-countable(arg),
message: "expected " + arg-name + "to be one of heading, page, math.equation or figure, but got " + str(type(arg))
)
}

#let get-countable-parameters(c) = {
assert-countable(c)
assert-countable(c, "c")

let counter = if c.func() == heading {
counter(heading)
Expand Down Expand Up @@ -45,24 +44,36 @@
)
}

#let is-numbered(c) = {
if is-countable(c) {
let params = get-countable-parameters(c)
/// Check if argument is numbered.
/// That means it is one of
/// `heading`, `page`, `math.equation` or `figure`
/// and its numbering is not `none`.
///
/// - n (any):
/// -> bool
#let is-numbered(n) = {
if is-countable(n) {
let params = get-countable-parameters(n)
return params.numbering != none
}
return false
}

#let assert-numbered(c) = {
#let assert-numbered(arg, arg-name) = {
assert(
is-numbered(c),
message: "expected numbered countable"
is-numbered(arg),
message: "expected " + arg-name + " to be numbered, but got " + str(type(arg))
)
}

#let display-countable(c) = {
assert-numbered(c)
/// Display the numbering of the argument
/// at its location.
///
/// - n (numbered):
/// -> content
#let display-numbered(n) = {
assert-numbered(n, "n")

let params = get-countable-parameters(c)
let params = get-countable-parameters(n)
numbering(params.numbering, ..params.counter.at(params.location))
}
17 changes: 13 additions & 4 deletions src/reset-counter.typ
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,23 @@
functions.fold((c => c), (f, g) => (c => f(g(c))))
}

// Reset theorem group counter to zero.
/// Reset theorem group counter to zero.
/// The result needs to be added to the document.
///
/// - kind-func (kind-function): The group is obtained from this kind function.
/// -> content
#let reset-counter(kind-func) = {
assert-type(kind-func, "kind-func", function)
counter(select-group(kind-func)).update(c => 0)
return counter(select-group(kind-func)).update(c => 0)
}

// Reset counter of specified theorem group
// on headings with at most the specified level.
/// Reset counter of theorem group
/// on headings with at most the specified level.
///
/// - kind-func (kind-function): The group is obtained from this kind function.
/// - max-level (int): Should be at least 1.
/// - content (content):
/// -> content
#let reset-counter-heading(
kind-func,
max-level,
Expand Down
20 changes: 20 additions & 0 deletions src/selectors.typ
Original file line number Diff line number Diff line change
@@ -1,6 +1,14 @@
#import "types.typ": assert-type, None
#import "theorem.typ": get-theorem-parameters

// TODO: implement ignore-unnumbered
/// Selector-function which selects the last
/// heading.
///
/// - ignore-unnumbered (bool): Use the first heading which is numbered.
/// - max-level (int, none): TODO
/// - loc (location):
/// -> heading, none
#let last-heading(
ignore-unnumbered: false,
max-level: none,
Expand Down Expand Up @@ -37,12 +45,24 @@
}
}

/// Generate selector that selects all
/// theorems of the same group as the
/// argument.
///
/// - kind-func (kind-function):
/// -> selector
#let select-group(kind-func) = {
assert-type(kind-func, "kind-func", function)
let params = get-theorem-parameters(kind-func[])
return figure.where(kind: params.group)
}

/// Generate selector that selects only
/// theorems that were create from
/// the provided `kind-function`.
///
/// - kind-func (kind-function):
/// -> selector
#let select-kind(kind-func) = {
assert-type(kind-func, "kind-func", function)

Expand Down
32 changes: 26 additions & 6 deletions src/styles.typ
Original file line number Diff line number Diff line change
@@ -1,16 +1,28 @@
#import "theorem.typ": resolve-link, get-theorem-parameters, is-theorem
#import "countable.typ": display-countable, is-numbered
#import "numbered.typ": display-numbered, is-numbered
#import "types.typ": assert-type

// TODO: assert type of seperator here
/// If the linked content is numbered combine it with the numbering
/// of the theorem.
///
/// - thm (theorem):
/// - referenced (bool):
/// - seperator (content, str): The sepeartor is put between both numberings.
#let numbering-concat(thm, referenced, seperator: ".") = {
assert-type(seperator, "seperator", content, str)
let linked = resolve-link(thm)
if linked != none and is-numbered(linked) {
display-countable(linked)
display-numbered(linked)
seperator
}
display-countable(thm)
display-numbered(thm)
}

/// Copy the numbering of a linked `theorem` if referenced.
/// Otherwise no numbering is returned.
///
/// - thm (theorem):
/// - referenced (bool):
#let numbering-proof(thm, referenced) = {
let linked = resolve-link(thm)
if referenced and linked != none {
Expand All @@ -20,8 +32,12 @@
}
}

// TODO: assert type of qed
/// Simple theorem style. Check the documentation for images.
///
/// - thm (theorem):
/// - qed (bool): Select if a box should be shown at the end.
#let style-simple(thm, qed: false) = {
assert-type(qed, "qed", bool)
let params = get-theorem-parameters(thm)
block(width: 100%, breakable: true, {
strong(params.kind-name)
Expand All @@ -41,8 +57,12 @@
})
}

// TODO: assert type of qed
/// Reverses numbering and `kind-name`.
///
/// - thm (theorem):
/// - qed (bool): Select if a box should be shown at the end.
#let style-reversed(thm, qed: false) = {
assert-type(qed, "qed", bool)
let params = get-theorem-parameters(thm)
block(width: 100%, breakable: true, {
if params.numbering != none {
Expand Down
Loading

0 comments on commit bd0be91

Please sign in to comment.