Keep it tidy.
tidy is a package that generates documentation directly in Typst for your Typst modules. It parses docstring comments similar to javadoc and co. and can be used to easily build a beautiful reference section for the parsed module. Within the docstring you may use (almost) any Typst syntax − so markup, equations and even figures are no problem!
Features:
- Customizable output styles.
- Automatically render code examples.
- Annotate types of parameters and return values.
- Automatically read off default values for named parameters.
- Help feature for your package.
- Docstring tests.
The guide fully describes the usage of this module and defines the format for the docstrings.
Using tidy is as simple as writing some docstrings and calling:
#import "@preview/tidy:0.3.0"
#let docs = tidy.parse-module(read("my-module.typ"))
#tidy.show-module(docs, style: tidy.styles.default)The available predefined styles are currenty tidy.styles.default and tidy.styles.minimal. Custom styles can be added by hand (take a look at the guide).
A full example on how to use this module for your own package (maybe even consisting of multiple files) can be found at examples.
/// This function computes the cardinal sine, $sinc(x)=sin(x)/x$.
///
/// #example(`#sinc(0)`, mode: "markup")
///
/// - x (int, float): The argument for the cardinal sine function.
/// -> float
#let sinc(x) = if x == 0 {1} else {calc.sin(x) / x}tidy turns this into:
The code in the docstrings is evaluated via eval(). In order to access user-defined functions and images, you can make use of the scope argument of tidy.parse-module():
#{
import "my-module.typ"
let module = tidy.parse-module(read("my-module.typ"))
let an-image = image("img.png")
tidy.show-module(
module,
style: tidy.styles.default,
scope: (my-module: my-module, img: an-image)
)
}The docstrings in my-module.typ may now access the image with #img and can call any function or variable from my-module in the style of #my-module.my-function(). This makes rendering examples right in the docstrings as easy as a breeze!
With tidy, you can add a help command to you package that allows users to obtain the documentation of a specific definition or parameter right in the document. This is similar to CLI-style help commands. If you have already written docstrings for your package, it is quite low-effort to add this feature. Once set up, the end-user can use it like this:
// happily coding, but how do I use this one complex function again?
#mypackage.help("func")
#mypackage.help("func(param1)") // print only parameter description of param1This will print the documentation of func directly into the document — no need to look it up in a manual. Read up in the guide for setup instructions.
It is possible to add simple docstring tests — assertions that will be run when the documentation is generated. This is useful if you want to keep small tests and documentation in one place.
/// #test(
/// `num.my-square(2) == 4`,
/// `num.my-square(4) == 16`,
/// )
#let my-square(n) = n * nWith the short-hand syntax, a unfulfilled assertion will even print the line number of the failed test:
/// >>> my-square(2) == 4
/// >>> my-square(4) == 16
#let my-square(n) = n * nA few test assertion functions are available to improve readability, simplicity, and error messages. Currently, these are eq(a, b) for equality tests, ne(a, b) for inequality tests and approx(a, b, eps: 1e-10) for floating point comparisons. These assertion helper functions are always available within docstring tests (with both test() and >>> syntax).
- New features:
- Help feature.
preambleoption for examples (e.g., to addimportstatements).- more options for
show-module:omit-private-definitions,omit-private-parameters,enable-cross-references,local-names(for configuring language-specific strings).
- Improvements:
- Allow using
show-example()as standalone. - Updated type names that changed with Typst 0.8.0, e.g., integer -> int.
- Allow using
- Fixes:
- allow examples with ratio widths if
scale-previewis notauto. show-outline- explicitly use
raw(lang: none)for types and function names.
- allow examples with ratio widths if
- New features:
- Add executable examples to docstrings.
- Documentation for variables (as well as functions).
- Docstring tests.
- Rainbow-colored types
colorandgradient.
- Improvements:
- Allow customization of cross-references through
show-reference(). - Allow customization of spacing between functions through styles.
- Allow color customization (especially for the
defaulttheme).
- Allow customization of cross-references through
- Fixes:
- Empty parameter descriptions are omitted (if the corresponding option is set).
- Trim newline characters from parameter descriptions.
⚠️ Breaking changes:- Before, cross-references for functions using the
@@syntax could omit the function parentheses. Now this is not possible anymore, since such references refer to variables now. - (only concerning custom styles) The style functions
show-outline(),show-parameter-list, andshow-type()now takestyle-argsarguments as well.
- Before, cross-references for functions using the
Initial Release.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent