tidy:0.3.0

[fossil sequoia]

Hi everyone 📃,

Tidy is a docs generator for Typst packages.

tidy:0.3.0 is available! If you're not using it, this release might change your mind ;) because now, tidy assists you in creating a help() command for your package. The help command 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 such a command.

The package quill already uses this feature. Try for example typing

#import "@preview/quill:0.3.0"

#quill.help("gate")

Read up in the guide (see below) for instructions on setting up a help() command for your package. Note: this feature is still experimental and awaiting feedback! Also, it would hugely benefit from user-defined types (for custom set and show rules), so that the end-user could customize the output.

https://typst.app/universe/package/tidy

You can read the guide here
https://github.com/Mc-Zen/tidy/releases/download/v0.3.0/tidy-guide.pdf
and import the package via #import "@preview/tidy:0.3.0".

Full Changelog:

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

[wanton pivot]

I have a function which uses the ..spread operator for all its arguments. I do my own input validation based on that. Would it be possible to add an option to ignore the assert in https://github.com/Mc-Zen/tidy/blob/main/src/tidy-parse.typ#L325 and let me specify the argument list myself?

[fossil sequoia]

@wanton pivot Ah, okay so you delegate to another function and don't want to repeat all the arguments?

It would be possible. Beware, however, it's not possible to read off the default values in this case! The parser wouldn't even know if the arguments are positional or named.

In the case that does not happen too often, I personally copy the entire signature because the maintenance overhead is little compared to the gains in code clearity and advantages in documentation.

[wanton pivot]

Yes, basically like this:

#let fun(..args) = {
  let processed-args = bar(args)
  // ...
}

bar(args) iterates through all the named arguments and does its own argument processing, in my case with custom error messages/warnings within the PDF document. My arguments are actually within a dictionary.

I guess I could just recreate the function with the intended signature, yeah.

[halcyon tulip]

It's one of the features I'd like to add to the Valkyrie package in the medium future

[wanton pivot]

Nice. I found that error messages at the beginning of the document are easier to read and process than ones that appear (in the terminal) one at a time. My template also has a draft parameter which controls whether the document can be compiled (if draft is enabled, display errors in document, otherwise do not compile)

[halcyon tulip]

I reckon this draft parameter should be a natively supported feature (perhaps as binary flags)

[wanton pivot]

any idea why #example doesn't work here?

I used the official example. It should know about sinc, no?

[halcyon tulip]

You need to pass sinc through scope

[fossil sequoia]

Indeed, you should do it like this:

#import "sinc.typ" // no * here!
...
#tidy.show-module(
  docs, 
  scope: (sinc: sinc)
)