typst-doc

Convert Man Pages to Typst

Python · R · Typst · CLI

Render R, Python, Typst, and Unix manual-page documentation as Typst. One reader per input language, one writer, one intermediate representation in between.

API reference: the typst-doc manual page, rendered by typst-doc itself.

Install

Prebuilt binaries are attached to every release:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/vincentarelbundock/typst-doc/releases/latest/download/typst-doc-installer.sh | sh

On Windows:

powershell -ExecutionPolicy Bypass -c "irm https://github.com/vincentarelbundock/typst-doc/releases/latest/download/typst-doc-installer.ps1 | iex"

Or build from source:

cargo install --git https://github.com/vincentarelbundock/typst-doc

Rendering the generated documents needs the Typst CLI on your PATH. Nothing else: typst-doc shells out to no other tool.

Usage

Every input is a file or a directory, and every documented entity becomes one manual entry. A directory contributes its recognised files in name order.

# One R help file, printed to standard output
typst-doc man/mean_ci.Rd

# A whole directory, joined into one document
typst-doc man/ > reference.typ

# Or one file per topic, plus an index.typ including them all
typst-doc R/ -o reference/
typst compile reference/index.typ

Cross-references resolve within a run: a link, or an author-written @name in a Typst doc comment, becomes a real link to the entry it names. Where two topics share a name the nearest wins, the same file before the same directory; a name this run does not define, or one that stays ambiguous from where it was written, renders as plain code and is reported. Internal topics are skipped unless --include-internal is passed.

R

.Rd files, the format R CMD check validates and ?help displays. Parsing is done by rd-source and rd-ast, eitsupi’s Rust crates, which tokenise an .Rd file and hand back its macro tree.

typst-doc man/ -o reference/

Rd is a typed markup language, so the reader has the most to work with: \arguments, \value, \seealso, \examples, and the rest map directly onto manual sections. \eqn/\deqn are LaTeX, so they go through MiTeX. \out{} becomes html.elem, guarded by target() so the same file still compiles to PDF. R code becomes a highlighted raw block, never an executable one, and \keyword{internal}, the signal pkgdown filters on, marks a topic internal.

Python

Modules and packages, with numpydoc-style docstrings.

typst-doc mypkg/ -o reference/

A docstring is the signal that an entity is documentation-worthy: undocumented definitions are not listed. Parameters, Returns, See Also, and Examples route to the matching sections, long signatures are broken across lines, and names starting with _ are private, though dunders like __init__ stay public.

A package is read the way Python imports it: every topic is named under the packages above it, so fit in mypkg/core.py is mypkg.core.fit, and an __init__.py documents its own package. How far the dotted name reaches is decided by the highest __init__.py above the file, so a PEP 420 namespace subpackage belongs to the path without one of its own, while a loose module in a plain directory keeps its bare stem.

Typst

Packages documented with /// comments, in the convention established by the tidy package.

typst-doc src/lib.typ -o reference/
/// Creates one logical slide command.
///
/// = Examples
///
/// ```typ
/// #mosaic.slide[Hello]
/// ```
///
/// -> content
#let slide(
  /// Which layout resolves this slide.
  /// -> auto | str | dictionary
  layout: auto,
  ..bodies
) = { }

When the input is a package (a typst.toml at it or above it), the entry point is read, and each definition is named by the path a user imports it under: image when lib.typ re-exports it plainly, layout.image when behind a module alias. A Typst module cannot bind two things to one name, so those names are unique by construction, and what the entry point never mentions is not public: unexported definitions are skipped as internal, or kept with --include-internal.

Existing tidy comments parse unchanged. The dialect diverges in three deliberate ways: type annotations are line-anchored to a final -> line, level-1 headings such as = Value and = Details route to the matching manual section, and only documented definitions become entries. Defaults are sliced from the source, so the author’s formatting survives.

Man pages

roff in the man(7) macro package: the .TH, .SH, .TP, .B vocabulary every Linux page is written in. Inputs are selected by section number, or the .man extension.

zcat /usr/share/man/man1/ls.1.gz > ls.1
typst-doc ls.1 -o ls.typ

A man page carries no machine-readable structure below the section level, so the reader infers it: roff lines become blocks, a run of .TP items becomes a term list, and the section titles route each part to the field it belongs in. NAME gives the topic name, SYNOPSIS the signature, anything ending in OPTIONS the parameters, RETURN VALUE and EXIT STATUS the value. Unrecognised sections keep their own heading rather than being guessed at, and ls(1) in SEE ALSO is a cross-reference, exactly like an Rd \link.

Both macro packages are read: presentational man(7), whose structure has to be inferred, and mdoc(7), the BSD and macOS default, which names what each thing is and is taken at its word. A .so stub is a redirect rather than a page, and scanning skips one with a warning.

Templates

Every generated document is in two halves: a data block, and a template that renders it.

#let doc-title = [Confidence interval for a mean]
#let doc-signature = ```r
mean_ci(x, level = 0.95)
```
#let doc-params = (
  (names: ("x",), type: "numeric", default: none, optional: false,
   body: [A numeric vector.]),
)
#let doc-sections = (
  (id: "description", title: [Description], kind: "prose", body: [...]),
  (id: "arguments", title: [Arguments], kind: "params", items: doc-params),
)

// ... the template, rendering those bindings ...

The first half is what the entry says; the second is the only thing that decides how it looks. So there are no styling options: to change how a manual is typeset, replace the template.

typst-doc man/ -o reference/
typst-doc man/ --template mine.typ -o reference/

The template is inlined rather than imported, so every entry compiles on its own with no file beside it. Each one therefore carries its own copy, which is a fair price for a directory of self-contained documents. The one exception is LaTeX math: an entry containing an \eqn imports MiTeX, because Typst math cannot read LaTeX. Nothing else is ever imported.

The data

Every binding is defined by every entry, empty where the topic has nothing, so a template that reads doc-examples cannot break on the one entry that has none.

BindingTypeHolds
doc-namestrthe topic’s identifier
doc-labellabel or nonethe heading’s cross-reference target
doc-titlecontentthe one-line title
doc-aliasesarraystrings: other names the topic answers to
doc-sourcestr or nonethe file, when a name is shared
doc-signaturecontent or nonehow the entity is called
doc-paramsarraydictionaries: names, type, default, optional, body
doc-raisesarraydictionaries, shaped like doc-params
doc-examplesarraydictionaries: run, code
doc-sectionsarraydictionaries: the whole entry, in order

The code bindings are raw blocks, so a template that wants to rebuild one has doc-signature.lang and .text to hand, and the same on each example’s code.

Write against doc-sections. It is the entry in order, each section tagged with what it holds ("prose" with a body, or "params" or "examples" with items), and sections the topic does not have are simply absent. One loop renders everything, with no emptiness guards:

#for section in doc-sections {
  heading(level: 2, section.title)
  if section.kind == "prose" { section.body }
  else if section.kind == "params" { my-params(section.items) }
  else if section.kind == "examples" { my-examples(section.items) }
}

Because the order is data rather than control flow, reordering sections, retitling them, or translating their headings is list manipulation, not an edit to the loop.

A complete entry

Here is a whole data block, as typst-doc emits it: one entry filled in with every field a topic can have. A template is inlined below a block of exactly this shape.

#let doc-name = "mean_ci"
#let doc-label = <mean_ci>
#let doc-title = [Confidence interval for a mean]
#let doc-aliases = ("mean_ci",)
#let doc-source = none
#let doc-signature = ```r
mean_ci(x, level = 0.95)
```
#let doc-params = (
  (names: ("x",), type: "numeric", default: none, optional: false, body: [A numeric vector\.]),
  (names: ("level",), type: "numeric", default: "0.95", optional: true, body: [Coverage probability\.]),
)
#let doc-raises = (
  (names: ("ValueError",), type: none, default: none, optional: false, body: [If x is empty\.]),
)
#let doc-examples = (
  (run: true, code: ```r
mean_ci(rnorm(100))
```),
  (run: false, code: ```r
mean_ci(x, level = 0.99)
```),
)
#let doc-sections = (
  (id: "description", title: [Description], kind: "prose", body: [
Computes a normal-approximation confidence interval\.
  ]),
  (id: "arguments", title: [Arguments], kind: "params", items: doc-params),
  (id: "details", title: [Details], kind: "prose", body: [
The interval is symmetric about the sample mean\.
  ]),
  (id: "value", title: [Value], kind: "prose", body: [
A numeric vector of length two\.
  ]),
  (id: "raises", title: [Raises], kind: "params", items: doc-raises),
  (id: "custom", title: [Caveats], kind: "prose", body: [
An unrecognised section keeps its own heading\.
  ]),
  (id: "note", title: [Note], kind: "prose", body: [
Assumes approximate normality\.
  ]),
  (id: "examples", title: [Examples], kind: "examples", items: doc-examples),
  (id: "seealso", title: [See Also], kind: "prose", body: [
t\.test
  ]),
  (id: "references", title: [References], kind: "prose", body: [
Casella and Berger \(2002\)\.
  ]),
  (id: "author", title: [Author], kind: "prose", body: [
A\. Person
  ]),
)

A real entry differs only in what it has: the bindings are all there either way, empty where the topic said nothing.

The default template

This is the template every manual is built with unless --template says otherwise, and it is short enough to read in one sitting. Two helpers, then one loop over doc-sections.

#let doc-render-params(items) = table(
  columns: 2,
  stroke: none,
  ..items
    .map(param => (
      raw(param.names.join(", ")),
      if param.type == none { param.body } else [#raw(param.type) \ #param.body],
    ))
    .flatten()
)

#let doc-render-examples(items) = items.map(example => example.code).join(parbreak())

#heading(level: 1, doc-title) #doc-label

#doc-signature

#if doc-source != none [
  #emph[Defined in] #raw(doc-source)
]

#for section in doc-sections {
  heading(level: 2, section.title)
  if section.kind == "prose" {
    section.body
  } else if section.kind == "params" {
    doc-render-params(section.items)
  } else if section.kind == "examples" {
    doc-render-examples(section.items)
  }
}

Writing one

A run writes the manual and nothing else. To start from the default rather than a blank file, ask for it:

typst-doc man/ --template-starter -o reference/
cp reference/template-default.typ mine.typ

That writes template-default.typ beside the manual: the template above, with the binding table repeated as a comment header. It is the template that produced the manual next to it, so passing it back with --template reproduces the same output exactly, which makes it a working starting point rather than a sketch. It is overwritten whenever the flag is given, so edit a copy under another name.

Preview that copy against the entry above. Save the data block to example-data.typ; the two files are a complete document once concatenated, so you can see the result without building a manual first:

cat example-data.typ mine.typ | typst compile - preview.pdf

When it looks right, build the manual with it:

typst-doc man/ --template mine.typ -o reference/

Two things to know while editing. Names beginning with doc- belong to the data contract, so give a template’s own helpers any other name. And a template is code rather than markup, so a mistyped binding is caught when Typst compiles the manual, not when typst-doc writes it.

Output validity

The writer emits strings, so typst-syntax, Typst’s own parser, doubles as a validator: every test asserts that generated markup parses with no errors. The same check runs over a whole directory of .Rd, .py, .typ, or man page files, and over the fixture corpus in CI on every push:

cargo run --example validate -- tests/corpus