Tidy

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.
Call your own module's code within the docstring, e.g., to render examples.
Annotate types of parameters and return values.
Automatically read off default values for named parameters.
Docstring tests.

The guide describes the usage of this module and defines the format for the docstrings.

Usage

Using tidy is as simple as writing some docstrings and calling:

#import "@preview/tidy:0.2.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 (see the guide).

Furthermore, it is possible to access user-defined functions and use images through 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!

Example

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 does something. It always returns true.
///
/// We can have *markdown* and 
/// even $m^a t_h$ here. A list? No problem:
///  - Item one 
///  - Item two 
/// 
/// - param1 (string): This is param1.
/// - param2 (content, length): This is param2.
///           Yes, it really is. 
/// - ..options (any): Optional options. 
/// -> boolean, none
#let something(param1, param2: 3pt, ..options) = { return true }

tidy turns this into:

Changelog

v0.2.0

New features:
- Add executable examples to docstrings.
- Documentation for variables (as well as functions).
- Docstring tests.
- Rainbow-colored types color and gradient.
Improvements:
- Allow customization of cross-references through show-reference().
- Allow customization of spacing between functions through styles.
- Allow color customization (especially for the default theme).
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, and show-type() now take style-args arguments as well.

v0.1.0

Initial Release.

Mc-Zen / tidy