Tidy

Keep it tidy.

tidy is a package that generates documentation directly in Typst for your Typst modules. It parses doc-comments and can be used to easily build a reference section for a module. Doc-comments use Typst syntax − so markup, equations and even figures are no problem!

Important

In version 0.4.0, the default documentation syntax has changed. You can take a look at the migration guide or revert to the old syntax with tidy.parse-module(old-syntax: true, ...).

You can still find the documentation for the old syntax in the 0.3.0 user guide.

Features:

• Customizable output styles.
• Automatically preview code examples.
• Annotate types of parameters and return values.
• Cross-references to definitions and function parameters.
• Automatically read off default values for named parameters.
• Help feature for your package.
• Doc-tests.

The guide fully describes the usage of this module and defines documentation syntax.

Usage

Using tidy is as simple as writing some doc-comments and calling:

#import "@preview/tidy:0.4.0"

#let docs = tidy.parse-module(read("my-module.typ"))
#tidy.show-module(docs, style: tidy.styles.default)

The available predefined styles are currently tidy.styles.default and tidy.styles.minimal. Custom styles can be added by hand (take a look at the user guide).

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 computes the cardinal sine, $sinc(x)=sin(x)/x$. 
///
/// ```example
/// #sinc(0)
/// ```
///
/// -> float
#let sinc(
  /// The argument for the cardinal sine function. 
  /// -> int | float
  x
) = if x == 0 {1} else {calc.sin(x) / x}

tidy turns this into:

Access user-defined functions and images

The code in the doc-comments is evaluated through the eval function. 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 doc-comments 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 doc-comments as easy as a breeze!

Generate a help command for you package

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 doc-comments 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 param1

This will print the documentation of func directly into the document — no need to look it up in a manual. Read up on setup instructions in the user guide.

Doc-tests

It is possible to add simple doc-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 * n

A 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 doc-comment tests.

Changelog

v0.4.0

Major redesign of the documentation syntax

• New features
  • New parser for the new documentation syntax. The old parser is still available and can be activated via tidy.parse-module(old-syntax: true). There is a migration guide for adopting the new syntax.
  • Cross-references to function arguments.
  • Support for detecting curried functions, i.e., function aliases with prepended arguments using the .with() function.

v0.3.0

Adds a help feature and more options

• New features:
  • Help feature.
  • preamble option for examples (e.g., to add import statements).
  • 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.
• Fixes:
  • allow examples with ratio widths if scale-preview is not auto.
  • show-outline
  • explicitly use raw(lang: none) for types and function names.

v0.2.0

• New features:
  • Add executable examples to doc-comments.
  • Documentation for variables (as well as functions).
  • Doc-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