{"id":23390847,"url":"https://github.com/Mc-Zen/tidy","last_synced_at":"2025-08-24T10:31:05.365Z","repository":{"id":173672816,"uuid":"650619965","full_name":"Mc-Zen/tidy","owner":"Mc-Zen","description":"A documentation generator for Typst in Typst.","archived":false,"fork":false,"pushed_at":"2024-07-26T10:03:09.000Z","size":1241,"stargazers_count":50,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-07-27T10:59:39.025Z","etag":null,"topics":["docs-generator","typst","typst-doc"],"latest_commit_sha":null,"homepage":"https://typst.app/universe/package/tidy","language":"Typst","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Mc-Zen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-07T12:59:15.000Z","updated_at":"2024-07-26T10:03:13.000Z","dependencies_parsed_at":null,"dependency_job_id":"c151c647-a50a-472c-8d7b-f59f11f6d11d","html_url":"https://github.com/Mc-Zen/tidy","commit_stats":null,"previous_names":["mc-zen/typst-doc"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mc-Zen%2Ftidy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mc-Zen%2Ftidy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mc-Zen%2Ftidy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mc-Zen%2Ftidy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mc-Zen","download_url":"https://codeload.github.com/Mc-Zen/tidy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230791033,"owners_count":18280714,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docs-generator","typst","typst-doc"],"created_at":"2024-12-22T04:00:39.384Z","updated_at":"2025-08-24T10:31:05.353Z","avatar_url":"https://github.com/Mc-Zen.png","language":"Typst","funding_links":[],"categories":["Credit","Typst"],"sub_categories":["5. Beyond"],"readme":"\n# Tidy\n*Keep it tidy.*\n\n[![Typst Package](https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fraw.githubusercontent.com%2FMc-Zen%2Ftidy%2Fv0.4.3%2Ftypst.toml\u0026query=%24.package.version\u0026prefix=v\u0026logo=typst\u0026label=package\u0026color=239DAD)](https://typst.app/universe/package/tidy)\n[![MIT License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/Mc-Zen/tidy/blob/main/LICENSE)\n[![Test Status](https://github.com/Mc-Zen/tidy/actions/workflows/run_tests.yml/badge.svg)](https://github.com/Mc-Zen/tidy/actions/workflows/run_tests.yml)\n[![User Manual](https://img.shields.io/badge/manual-.pdf-purple)][guide]\n\n\n\n\n**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!\n\n\u003e [!IMPORTANT]\n\u003e 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, ...)`. \n\u003e\n\u003e 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). \n\nFeatures:\n- **Customizable** output styles. \n- Automatically [**preview code examples**](#example). \n- **Annotate types** of parameters and return values.\n- **Cross-references** to definitions and function parameters. \n- Automatically read off default values for named parameters.\n- [**Help** feature](#generate-a-help-command-for-you-package) for your package. \n- [Doc-tests](#doc-tests). \n\n\nThe [guide][guide] fully describes the usage of this module and defines documentation syntax. \n\n## Usage\n\nUsing `tidy` is as simple as writing some doc-comments and calling:\n```typ\n#import \"@preview/tidy:0.4.3\"\n\n#let docs = tidy.parse-module(read(\"my-module.typ\"))\n#tidy.show-module(docs, style: tidy.styles.default)\n```\n\nThe 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]). \n\n## Example\n\nA 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).\n\n```typ\n/// This function computes the cardinal sine, $sinc(x)=sin(x)/x$. \n///\n/// ```example\n/// #sinc(0)\n/// ```\n///\n/// -\u003e float\n#let sinc(\n  /// The argument for the cardinal sine function. \n  /// -\u003e int | float\n  x\n) = if x == 0 {1} else {calc.sin(x) / x}\n```\n\n**tidy** turns this into:\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg alt=\"Tidy example output\" src=\"docs/images/sincx-docs.svg\" style=\"max-width: 100%; padding: 10px 10px; box-shadow: 1pt 1pt 10pt 0pt #AAAAAA; border-radius: 4pt; box-sizing: border-box; background: white\"\u003e\n\u003c/div\u003e\n\n\n## Access user-defined functions and images\n\nThe 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()`:\n\n```typ\n#{\n    import \"my-module.typ\"\n    let module = tidy.parse-module(read(\"my-module.typ\"))\n    let an-image = image(\"img.png\")\n    tidy.show-module(\n        module,\n        style: tidy.styles.default,\n        scope: (my-module: my-module, img: an-image)\n    )\n}\n```\nThe 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!\n\n## Generate a help command for you package\nWith **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:\n\n```typ\n// happily coding, but how do I use this one complex function again?\n\n#mypackage.help(\"func\")\n#mypackage.help(\"func(param1)\") // print only parameter description of param1\n```\n\nThis 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]. \n\n## Doc-tests\nIt 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. \n```typ\n/// #test(\n///   `num.my-square(2) == 4`,\n///   `num.my-square(4) == 16`,\n/// )\n#let my-square(n) = n * n\n```\n\u003c!-- With the short-hand syntax, a unfulfilled assertion will even print the line number of the failed test:\n```typ\n/// \u003e\u003e\u003e my-square(2) == 4\n/// \u003e\u003e\u003e my-square(4) == 16\n#let my-square(n) = n * n\n``` --\u003e\nA 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. \n\n\n## Changelog\n\n### v0.4.3\n_Automatic locale support_\n- Tidy now detects the document language and adjusts words like \"Parameters\" and \"Default\" accordingly. It is still possible to set these values manually through the parameter `show-module.local-names`. \n- The word `Variables` can now also be customized. \n\n### v0.4.2\n_Fixes and Improvements_\n- Code examples can now also show code that is _not_ executed on lines starting with `\u003c\u003c\u003c`. \n- The type `tiling` is now supported and it is shown with the new gradient. \n- Fixes formatting of multiline default arguments. \n\n### v0.4.1\n_Fixes_\n- Strings containing `\"//\"` can now be used in default arguments.\n- References like `@section` can now link to labels outside the documentation. \n- Fixes issues with upcoming Typst 0.13.\n\n### v0.4.0\n_Major redesign of the documentation syntax_\n- New features\n  - 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. \n  - Cross-references to function arguments.\n  - Support for detecting _curried functions_, i.e., function aliases with prepended arguments using the `.with()` function. \n  \n\n### v0.3.0\n_Adds a help feature and more options_\n- New features:\n  - Help feature. \n  - `preamble` option for examples (e.g., to add `import` statements). \n  - more options for `show-module`: `omit-private-definitions`, `omit-private-parameters`, `enable-cross-references`, `local-names` (for configuring language-specific strings). \n- Improvements:\n  - Allow using `show-example()` as standalone. \n  - Updated type names that changed with Typst 0.8.0, e.g., integer -\u003e int. \n- Fixes:\n  - allow examples with ratio widths if `scale-preview` is not `auto`.\n  - `show-outline`\n  - explicitly use `raw(lang: none)` for types and function names. \n\n### v0.2.0\n- New features:\n  - Add executable examples to doc-comments. \n  - Documentation for variables (as well as functions). \n  - Doc-tests. \n  - Rainbow-colored types `color` and `gradient`. \n- Improvements:\n  - Allow customization of cross-references through `show-reference()`. \n  - Allow customization of spacing between functions through styles. \n  - Allow color customization (especially for the `default` theme). \n- Fixes:\n  - Empty parameter descriptions are omitted (if the corresponding option is set). \n  - Trim newline characters from parameter descriptions. \n- ⚠️ Breaking changes:\n  - 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. \n  - (only concerning custom styles) The style functions `show-outline()`, `show-parameter-list`, and `show-type()` now take `style-args` arguments as well. \n\n### v0.1.0\n\n_Initial Release_\n\n[guide]: https://github.com/Mc-Zen/tidy/releases/download/v0.4.3/tidy-guide.pdf\n\n[migration guide]: https://github.com/Mc-Zen/tidy/tree/v0.4.3/docs/migration-to-0.4.0.md","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMc-Zen%2Ftidy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMc-Zen%2Ftidy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMc-Zen%2Ftidy/lists"}