jneug / typst-mantys Goto Github PK

View Code? Open in Web Editor NEW

38.0 1.0 5.0 6.01 MB

Template for documenting Typst Packages and Templates.

License: MIT License

Typst 100.00%

typst-mantys's Introduction

Mantys (v0.1.4)

MANuals for TYpSt

Template for documenting typst packages and templates.

Usage

Just import the package at the beginning of your manual:

#import "@preview/mantys:0.1.4": *

Mantys supports Typst 0.11.0 and newer.

Writing basics

A basic template for a manual could look like this:

#import "@local/mantys:0.1.4": *

#import "your-package.typ"

#show: mantys.with(
	name:		"your-package-name",
	title: 		[A title for the manual],
	subtitle: 	[A subtitle for the manual],
	info:		[A short descriptive text for the package.],
	authors:	"Your Name",
	url:		"https://github.com/repository/url",
	version:	"0.0.1",
	date:		"date-of-release",
	abstract: 	[
		A few paragraphs of text to describe the package.
	],

	example-imports: (your-package: your-package)
)

// end of preamble

# About
#lorem(50)

# Usage
#lorem(50)

# Available commands
#lorem(50)

Use #command(name, ..args)[description] to describe commands and #argument(name, ...)[description] for arguments:

#command("headline", arg[color], arg(size:1.8em), sarg[other-args], barg[body])[
	Renders a prominent headline using #doc("meta/heading").

	#argument("color", type:"color")[
    The color of the headline will be used as the background of a #doc("layout/block") element containing the headline.
  ]
  #argument("size", default:1.8em)[
    The text size for the headline.
  ]
  #argument("sarg", is-sink:true)[
    Other options will get passed directly to #doc("meta/heading").
  ]
  #argument("body", type:"content")[
    The text for the headline.
  ]

  The headline is shown as a prominent colored block to highlight important news articles in the newsletter:

  #example[```
  #headline(blue, size: 2em, level: 3)[
    #lorem(8)
  ]
  ```]
]

The result might look something like this:

For a full reference of available commands read the manual.

Changelog

Version 0.1.5

Fixed #cmdref not showing command name (by @freundTech).
Made colors of datatype blocks look closer to the Typst website (by @tingerrr).

Version 0.1.4

Fix missing links in outline (@tingerrr).
Fixed problem when evaluating default values with Tidy.

Version 0.1.3

Fix for some datatypes not being displayed properly (thanks to @tingerrr).
Fix for imbalanced outline columns (thanks again to @tingerrr).

Version 0.1.2

Added hydra for better detection of headings in page headers (thanks to @tingerrr for the suggestion).
Fixed problem with multiple quotes around default string values in tidy docs.
Fixed datatypes linking to wrong documentation urls.

Version 0.1.1

Added template files for submission to Typst Universe.

Version 0.1.0

Refactorings and some style changes
Updated manual.
Restructuring of package repository.

Version 0.0.4

Added integration with tidy.
Fixed issue with types in argument boxes.
#lambda now uses #dtype

Breaking changes

Adapted scope argument for eval in examples.
- #example(), #side-by-side() and #shortex() now support the scope and mode argument.
- The option example-imports was replaced by examples-scope.

Version 0.0.3

It is now possible to load a packages' typst.toml file directly into #mantys:
```
 #show: mantys.with( ..toml("typst.toml") )
```
Added some dependencies:
- jneug/typst-tools4typst for some common utilities,
- jneug/typst-codelst for rendering examples and source code,
- Pablo-Gonzalez-Calderon/showybox-package for adding frames to different areas of a manual (like examples).
Redesign of some elements:
- Argument display in command descriptions,
- Alert boxes.
Added #version(since:(), until:()) command to add version markers to commands.
Styles moved to a separate theme.typ file to allow easy customization of colors and styles.
Added #func(), #lambda() and #symbol() commands, to handle special cases for values.
Fixes and code improvements.

Version 0.0.2

Some major updates to the core commands and styles.

Version 0.0.1

Initial release.

typst-mantys's People

Contributors

Stargazers

Watchers

Forkers

dvdtsb yssource sachink003 tingerrr freundtech

typst-mantys's Issues

Improve display of function and content values and types

The display of function and content values / types should be improved to get a better overview over the values content.

For arguments of type "function" a short signature should be generated. Details of complex function arguments could then be provided in the commands / arguments description.

Example

(content) -> content
(integer, any) -> none
(..integer) -> string

Odd display of non function items

I've noticed that the two .with declarations and a dictionary value are both displayed oddly:

Usually I'd fix this myself and make a PR, but I don't really know which part of the code is responsible for this.

README.md uses invalid syntax for sections

In section Writing basics of the README.md, the example should use = for headings.

# About
#lorem(50)

# Usage
#lorem(50)

# Available commands
#lorem(50)

Should be:

= About
#lorem(50)

= Usage
#lorem(50)

= Available commands
#lorem(50)

Links to built in types are 404

The generated link for the relative length type currently links to https://typst.app/docs/reference/types/relative, but this has been moved to https://typst.app/docs/reference/layout/relative/. I have not tested this for other types, but I assume they're a little out of date too.

Switching to 0.1.2 shows empty type highlights

After updating from 0.1.1 to 0.1.2 to fix the double quoting issue, I encountered the following problem:

Some types are completely empty despite being correctly highlighted.

`0.1.1`	`0.1.2`

String arguments are double escaped

String arguments get surrounded with double quotes two times, which results in output like

name: "\"aaa\""

Module outlines are unbalanced

Given a module outline that is not divisible by and greater than 3, the last row will be squished to the previous.

Label defined multiple times

I wanted to try out mantys for a new package I was working on and ran into an issue, the following code complained about the labels for the functions being defined multiple times:

#import "@preview/mantys:0.1.1": *

#import "/src/lib.typ" as subpar

#let package = toml("/typst.toml")

#show: mantys.with(
  ..package,
  title: [subpar],
  date: datetime.today().display(),
  abstract: [
    Subpar provides easy to use subfigures with sensible default numbering and related features like chapter-relative numbering in mind.
  ],
  example-scope: (subpar: subpar)
)

#tidy-module(read("/src/lib.typ"))

You can see the full repository at this point here.

Release as a template

With Typst 0.11.0 and Typst Universe, template packages are now accepted in the package repository.

I'd love to use this for my packages to get a clean and uniform look, but I'm not exactly thrilled about installing it locally, especially because this needlessly complicates my CI workflows too.

If you don't have time to prep this for release as a template, I'd be happy to write a PR that makes it template-ready.

Consider using non-proprietary fonts

Consider using a free equivalent for the proprietary font fallbacks use in the default config.

Especially in CI, where one would usually generate documentation automatically, installing fonts is a pain when they're not free. In general, the default theme should not assume a proprietary font is or can be installed, even if it is just a fallback.

A very dead-on free equivalent to Helvetica is Tex Gyre Heros.

Declaring and showing custom types

It would be great if one could register their own custom types that would be included in the theme.

In hydra, I have a section detailing dictionaries of certain shape that I pass around for internal use, and I give them names to use in the tidy doc-strings. These are currently not highlighted at all and if they were, I couldn't add my own dtype colors to the internal mantys theme.

Separately, it would be great if mantys had a canonical way to show custom types in the reference somewhere.

Mine currently look like this:

And used like this:

In the future, this will likely be superseded by actual types, but they too will need some kind of dedicated display function.

Section titles are shown on pages with new chapters/sections

When a page starts with a level 2 heading, it will still display the previous heading in the header, even when it doesn't have to.

This is obviously not a big problem, but a little ugly in my opinion.

I made a package for this called hydra (shameless plug) and here's how I fixed it in my own manual:
https://github.com/tingerrr/subpar/blob/main/doc/manual.typ#L28-L37