Version 0.4.0 (December 11, 2024)

This release is a major redesign of the documentation syntax, intending to pave the way for eventual built-in documentation support. There is a migration guide for adopting the new syntax.

Instead of (old)

/// This function computes the cardinal sine, $sinc(x)=sin(x)/x$. 
///
/// - x (int, float): The argument for the cardinal sine function. 
/// -> float
#let sinc(x) = if x == 0 {1} else {calc.sin(x) / x}

we now write (new)

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

The new style

• removes almost all extra syntax and makes use of pure Typst syntax (cross references are now handled via single @ instead of @@).
• moves the parameter descriptions right in front of each parameter.
• has a temporary syntax for type annotations that makes it relatively easy to switch to the built-in solution that we are expecting to have soon in Typst.

The old syntax

Note that you can also keep using the old syntax which will still be around for some time. It can be activated via tidy.show-module(old-syntax: true, ...).

New features

• New parser for the new documentation syntax. The old parser is still available and can be activated via tidy.show-module(old-syntax: true).
• Cross-references to function arguments.
• Support for detecting curried functions, i.e., function aliases with prepended arguments using the .with() function.
• Auto-previewed examples can now be written with

  ```example
  #rect()
  ```
  

  or

  ```examplec
  rect()
  ```
  

I'm happy to get feedback. Enjoy!

Version 0.3.0 (May 13, 2024)

The version 0.3.0 adds help command generation and various improvements.

• 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.

Version 0.2.0 (January 03, 2024)

The version 0.2.0 adds new features like convenient code example rendering and docstring testing as well as numerous improvements and fixes.

• 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.

Version 0.1.0 (August 7, 2023)

This is the first release of tidy, an in-Typst documentation generator for Typst code.