Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Mc-Zen/tidy
A documentation generator for Typst in Typst.
https://github.com/Mc-Zen/tidy
docs-generator typst typst-doc
Last synced: 29 days ago
JSON representation
A documentation generator for Typst in Typst.
- Host: GitHub
- URL: https://github.com/Mc-Zen/tidy
- Owner: Mc-Zen
- License: mit
- Created: 2023-06-07T12:59:15.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-07-26T10:03:09.000Z (6 months ago)
- Last Synced: 2024-07-27T10:59:39.025Z (6 months ago)
- Topics: docs-generator, typst, typst-doc
- Language: Typst
- Homepage: https://typst.app/universe/package/tidy
- Size: 1.18 MB
- Stars: 50
- Watchers: 1
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Tidy
*Keep it tidy.*
[](https://typst.app/universe/package/tidy)
[](https://github.com/Mc-Zen/tidy/blob/main/LICENSE)
[](https://github.com/Mc-Zen/tidy/actions/workflows/run_tests.yml)
[][guide]
**tidy** is a package that generates documentation directly in [Typst](https://typst.app/) 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][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](https://github.com/Mc-Zen/tidy/releases/download/v0.3.0/tidy-guide.pdf).
Features:
- **Customizable** output styles.
- Automatically [**preview code examples**](#example).
- **Annotate types** of parameters and return values.
- **Cross-references** to definitions and function parameters.
- Automatically read off default values for named parameters.
- [**Help** feature](#generate-a-help-command-for-you-package) for your package.
- [Doc-tests](#doc-tests).
The [guide][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:
```typ
#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][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](https://github.com/Mc-Zen/tidy/tree/main/examples).
```typ
/// 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`](https://typst.app/docs/reference/foundations/eval/) function. In order to access user-defined functions and images, you can make use of the `scope` argument of `tidy.parse-module()`:
```typ
#{
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:
```typ
// 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][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.
```typ
/// #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][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_
[guide]: https://github.com/Mc-Zen/tidy/releases/download/v0.4.0/tidy-guide.pdf
[migration guide]: https://github.com/Mc-Zen/tidy/tree/v0.4.0/docs/migration-to-0.4.0.md