Building Julia documentation using Typst

Internals & Design
1

I just wrote a Typst backend for Documenter.jl and managed to build the latest Julia documentation.

Footnotes are not supported yet, while math equations are kept as is since Typst uses a different grammar and there is no translator available at the moment.

A big advantage is the compilation speed. On my computer, the whole documentation can be compiled within ~13 min. And I believe there is still much room for improvement.

Official Typst does not support syntax highlighting for Julia yet, I have made a PR, but it is currently blocked by upstream packages. There are still some issues with syntax highlighting, e.g., in some cases, all code after # are taken as comments.

Resources:

32 Likes
2

Awesome stuff!
Don’t know how this initiative will turn out but I’m glad to see Typst take flight.

Quick nit:
this line will allocate furiously.

I think I would try

header_text = string("#extended_heading(level: ", depth, " within-block: false,  [", title," )])\n"

Because interpolation always copies. (If the copies are actually very heavy I’d stick the assignment in both places and inside the most nested loop, but YMMV.)

That said… I look forward to the compilation not taking ~13mins :sweat_smile: Happy perf hunting!

3 Likes
3

Actually, 13mins is already much faster than the LaTeX backend. But there is definitely much room for perf hunting.

Also, the bottleneck is the final compilation (.typ → .pdf), and the first step (MarkdownAST → .typ) is fast enough.

1 Like
4

Would it be possible to take advantage of Typst’s incremental compilation abilities and launch the compilation before the .typ document is finalized?

1 Like
5

Sorry if this is a daft question: what is the point of another backend (in addition to those that already exist)? These all output the same documents? Don’t they?

6

.

3 Likes
7

This is unnecessary since the generation of the .typ file is much faster than the compilation.

1 Like
8

Compilation of the PDF documentation took a lot of time in Julia’s CI. This is the reason why I started this experiment.

9

Interesting. Why exactly is it that Typst is much faster than Latex to produce PDF?

10

because it’s not LaTeX (doesn’t go through TeX at all)

11

I realize that. But why is the compilation into PDF faster?

12

Why is LaTeX so slow?

  • Takes about 40 minutes on my computer.
  • It takes about 30 minutes in GitHub action.

If all tex files are exported and compiled 3 times in draft mode using lualatex , it only takes about 4 minutes.
This means that about 90% of the time is spent on generating code highlights via the minted macro package.

Why typst is fast?

More incremental compilation-related descriptions can be found in ARCHITECTURE.md by searching for Incremental:
https://github.com/typst/typst/blob/main/ARCHITECTURE.md

1 Like
13

May be i am misunderstanding, but it sounded as if right now no coloring of code was done with Typst. And, the source code coloring with Pygments was the reason the build took so long. So how will things be better with Typst once one throws the syntax coloring in?

14

Typst uses syntect to do syntax highlighting, which is faster.

15

Did you benchmark that? Even the author seems to expect the speed of syntect and pygments to be comparable: Performance comparison · Issue #372 · trishume/syntect · GitHub

16

No, I have not benchmarked the two tools myself. There are cases where syntect has big advantages. For example,

image
image809×805 64.8 KB

bat uses syntect for syntax highlighting.

17

Just confirmed that the bottleneck is not syntax highlighting for typst. After turning off the outline, header, and footers (which are all implemented by myself), the compilation time is only 49s.

18

Another way of doing something? So what? That’s the whole point of progress, to explore new tools, find out their shortcomings, cure them if poss. and then we all have a choice: get rid or adopt! Brilliant! Long-live lateral exploration! :grinning:

10 Likes
19

Faster is very nice. But another advantage that is even more important for me is that Typst math syntax is a lot more readable uncompiled. Examples: there are no backslashes, no curly-braces, and a/b turns into a pretty fraction automatically. Why is that important?

Many docstrings include LaTeX to render nicely in the documentation. But often it is the only representation of some key mathematical relation, and it is really hard to read when you get the docstring in the REPL (or with mouse-over from a language server).

So math that both compiles pretty and is readable uncompiled for docstrings is something I would really love, and something Typst brings to the table.

8 Likes
20

That’s why I try to render the LaTeX in the REPL:


julia> function f end
f (generic function with 0 methods)

julia> @doc """
       Some function

       ``\\frac{1}{2}\\lvert\\alpha\\rvert + \\beta^2 - \\varphi``
       """ f
f

help?> f
search: f fd for fma fld fit fld1 fill fdio fit! frexp foldr foldl flush floor float first fill! fetch fldmod

  Some function

  ¹/₂|α| + β² − φ