[docs] update to 0.4.0 (#38)

README.md

@@ -2,35 +2,44 @@
 # Tidy
 *Keep it tidy.*
 
-[![Typst Package](https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fraw.githubusercontent.com%2FMc-Zen%2Ftidy%2Fmain%2Ftypst.toml&query=%24.package.version&prefix=v&logo=typst&label=package&color=239DAD)](https://typst.app/universe/package/tidy)
+[![Typst Package](https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fraw.githubusercontent.com%2FMc-Zen%2Ftidy%2Fv0.4.0%2Ftypst.toml&query=%24.package.version&prefix=v&logo=typst&label=package&color=239DAD)](https://typst.app/universe/package/tidy)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/Mc-Zen/tidy/blob/main/LICENSE)
+[![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)
 [![User Manual](https://img.shields.io/badge/manual-.pdf-purple)][guide]
 
 
-**tidy** is a package that generates documentation directly in [Typst](https://typst.app/) for your Typst modules. It parses docstring comments similar to javadoc and co. and can be used to easily build a beautiful reference section for the parsed module.  Within the docstring you may use (almost) any Typst syntax − so markup, equations and even figures are no problem!
+
+
+**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.show-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 [**render code examples**](#example). 
+- 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. 
-- [Docstring tests](#docstring-tests). 
+- [Doc-tests](#doc-tests). 
 
 
-The [guide][guide] fully describes the usage of this module and defines the format for the docstrings. 
+The [guide][guide] fully describes the usage of this module and defines documentation syntax. 
 
 ## Usage
 
-Using `tidy` is as simple as writing some docstrings and calling:
+Using `tidy` is as simple as writing some doc-comments and calling:
 ```typ
 #import "@preview/tidy:0.3.0"
 
 #let docs = tidy.parse-module(read("my-module.typ"))
 #tidy.show-module(docs, style: tidy.styles.default)
 ```
 
-The available predefined styles are currenty `tidy.styles.default` and `tidy.styles.minimal`. Custom styles can be added by hand (take a look at the [guide][guide]). 
+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
 
@@ -39,23 +48,28 @@ A full example on how to use this module for your own package (maybe even consis
 ```typ
 /// This function computes the cardinal sine, $sinc(x)=sin(x)/x$. 
 ///
-/// #example(`#sinc(0)`, mode: "markup")
+/// ```example
+/// #sinc(0)
+/// ```
 ///
-/// - x (int, float): The argument for the cardinal sine function. 
 /// -> float
-#let sinc(x) = if x == 0 {1} else {calc.sin(x) / x}
+#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:
 
-<h3 align="center">
+<div align="center">
   <img 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">
-</h3>
+</div>
 
 
 ## Access user-defined functions and images
 
-The code in the docstrings is evaluated via `eval()`. In order to access user-defined functions and images, you can make use of the `scope` argument of `tidy.parse-module()`:
+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
 #{
@@ -69,10 +83,10 @@ The code in the docstrings is evaluated via `eval()`. In order to access user-de
     )
 }
 ```
-The docstrings 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 docstrings as easy as a breeze!
+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 docstrings for your package, it is quite low-effort to add this feature. Once set up, the end-user can use it like this:
+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?
@@ -81,29 +95,38 @@ With **tidy**, you can add a help command to you package that allows users to ob
 #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 in the [guide][guide] for setup instructions. 
+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]. 
 
-## Docstring tests
-It is possible to add simple docstring 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. 
+## 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
 ```
-With the short-hand syntax, a unfulfilled assertion will even print the line number of the failed test:
+<!-- With the short-hand syntax, a unfulfilled assertion will even print the line number of the failed test:
 ```typ
 /// >>> my-square(2) == 4
 /// >>> 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 docstring tests (with both `test()` and `>>>` syntax). 
+``` -->
+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.show-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). 
@@ -118,9 +141,9 @@ A few test assertion functions are available to improve readability, simplicity,
 
 ### v0.2.0
 - New features:
-  - Add executable examples to docstrings. 
+  - Add executable examples to doc-comments. 
   - Documentation for variables (as well as functions). 
-  - Docstring tests. 
+  - Doc-tests. 
   - Rainbow-colored types `color` and `gradient`. 
 - Improvements:
   - Allow customization of cross-references through `show-reference()`. 
@@ -135,6 +158,8 @@ A few test assertion functions are available to improve readability, simplicity,
 
 ### v0.1.0
 
-Initial Release.
+_Initial Release_
+
+[guide]: https://github.com/Mc-Zen/tidy/releases/download/v0.4.0/tidy-guide.pdf
 
-[guide]: https://github.com/Mc-Zen/tidy/releases/download/v0.3.0/tidy-guide.pdf
+[migration guide]: https://github.com/Mc-Zen/tidy/tree/v0.4.0/docs/migration-to-0.4.0.md

docs/migration-to-0.4.0.md

@@ -0,0 +1,133 @@
+# Migration guide from 0.3.0 to 0.4.0 (new parser)
+
+
+If you choose to use the new documentation parser, this guide helps you with migrating your existing documentation to the new documentation syntax. Of course, 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, ...)`. 
+
+## Breaking changes
+
+Below you can find an overview over the breaking changes that the new syntax introduces. 
+
+- [Documentation of function arguments](#documentation-of-function-arguments)
+- [Cross-references](#cross-references)
+- [Example previews](#example-previews) (not strictly a breaking change)
+- [Doc-comment tests](#doc-comment-tests)
+
+
+### Documentation of function arguments
+
+In Tidy 0.3.0 and earlier, function arguments were all documented in a dedicated block that was part of the description doc-comment for the function, see below:
+```typ
+/// 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}
+```
+
+With the new syntax, the parameter description is moved right in front of the parameter declaration. The name of the parameter can thus be removed from the description. The type, however, is now annotated (until Typst provides built-in support for type annotations) just like the return type of the function itself with a trailing `->` expression. Also, multiple accepted types should now be separated with a pipe `|` operator instead of a comma (this also applies to the function return type). 
+
+The previous example thus becomes
+
+```typ
+/// 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}
+```
+Note that the trailing type annotation does not need to be on its own line. 
+
+
+### Cross-references
+
+In the old documentation style, there was a dedicated syntax for cross-references: the `@@` prefix. The new style uses just plain Typst references starting with a single `@`. In the case of cross-referencing a function, parentheses are never placed after the function name. *This is a breaking change to before when these parentheses were obligatory*. 
+
+In addition, it is now possible to reference a specific parameter of a function by appending a dot `.` and the parameter name, e.g., `sinc.x`. In order to use parameter references, the utilized template style needs to support them by creating appropriate labels for each parameter. The built-in style templates all support parameter referencing out of the box. 
+
+
+### Example previews
+
+A popular feature of Tidy is the example preview. A function, variable, or parameter description can contain demonstrating code examples that are automatically rendered and displayed side-by-side with the code. This used to be achieved through the `example()` function that Tidy provides since version 0.3.0. 
+
+Although this function is still available, we now encourage users to use a raw element with the language `example` (for Typst markdown mode) or `examplec` (for Typst code mode). 
+
+Thus, instead of 
+````typ
+/// This function computes the cardinal sine, $sinc(x)=sin(x)/x$. 
+///
+/// #example(`#sinc(0)`, mode: "markup")
+..
+````
+we can now simply write
+
+````typ
+/// This function computes the cardinal sine, $sinc(x)=sin(x)/x$. 
+///
+/// ```example
+/// #sinc(0)
+/// ```
+..
+````
+or
+````typ
+/// This function computes the cardinal sine, $sinc(x)=sin(x)/x$. 
+///
+/// ```examplec
+/// sinc(0)
+/// ```
+..
+````
+
+In all versions, you can insert _hidden_ code lines starting with `>>>` anywhere in the demo code. These lines will just be executed but not displayed. 
+````typ
+/// ```examplec
+/// >>> import my-math: sinc // just executed, not shown
+/// sinc(0)
+/// ```
+````
+This is useful for many scenarios like import statements, wrapping everything inside a container of a fixed size and other things.
+
+Look at the [default.typ](/src/styles/default.typ) template style for hints on customization of the example preview. 
+
+
+## Standalone usage of example previews
+
+Some people use the example preview feature to add self-compiling code examples independently of Tidy. This used to be possible via the following show rule:
+````typ
+#show raw: show-example.show-example
+
+```typ
+Hello world
+```
+````
+With the new version, this should be replaced with 
+```typ
+#import "@preview/tidy:0.4.0": render-examples
+#show: render-examples
+
+...
+```
+
+### Scope
+It also features a `scope` argument, that can be pre-set:
+
+````typ
+#show: render-examples.with(scope: (answer: 42))
+
+```example
+#answer
+```
+````
+
+
+### Customization
+The output format of the example can be customized through the parameter `layout` of `render-examples`. This parameter takes a `function` with two positional arguments: the `raw` element and the preview. 
+````typ
+#show: render-examples.with(layout: (code, preview) => grid(code, preview))
+````
+
+## Doc-comment tests
+Doc-comment tests can still be used as before but the short-hand syntax with `>>>` is no longer supported with the new documentation syntax. With `old-parser: true`, it is still available. 

docs/template.typ

@@ -21,10 +21,15 @@
   // set heading(numbering: (..args) => if args.pos().len() == 1 { numbering("I", ..args) })
   set heading(numbering: "I.a")
   show list: pad.with(x: 5%)
+  show heading.where(level: 3): set text(1.2em)
 
   // show link: set text(fill: purple.darken(30%))
-  show link: set text(fill: rgb("#1e8f6f"))
-  show link: underline
+  show link: it => {
+    let dest = str(it.dest)
+    if "." in dest and not "/" in dest { return underline(it, stroke: luma(60%), offset: 1pt) }
+    set text(fill: rgb("#1e8f6f")) 
+    underline(it)
+  }
 
   v(4em)
 
@@ -68,8 +73,10 @@
 
   // Main body.
   set par(justify: true)
-  v(10em)
+  v(7em)
 
+  pad(x: 10%, outline(depth: 2, indent: 2em))
+  pagebreak()
 
   show: codly-init.with(
   )
@@ -97,7 +104,7 @@
   stroke: rgb("#239DAE") + 1pt,
   radius: 3pt,
   {
-    block(align(right, text(raw(filename))), width: 100%, inset: 5pt)
+    block(align(right, text(raw(filename, lang: "cmd"))), width: 100%, inset: 5pt)
     v(1pt, weak: true)
     move(dx: -1pt, line(length: 100% + 2pt, stroke: 1pt + rgb("#239DAE")))
         v(1pt, weak: true)
@@ -106,16 +113,22 @@
 ))
 
 
-#let tidy-output-figure(output) = no-codly({
+#let tidy-output-figure(
+  output, 
+  breakable: false,
+  fill: none
+) = no-codly({
   set heading(numbering: none)
   set text(size: .8em)
-  figure(align(left, box(
+  show figure: set block(breakable: breakable)
+  figure(align(left, block(
     width: 80%,
+    fill: fill,
     stroke: 0.5pt + luma(200), 
     inset: 20pt, 
     radius: 10pt,
     block(
-      breakable: false,
+      breakable: breakable,
       output
     )
   )))