chore: support typst backend for docs

[Al3cLee]

What is changed?

This PR:

• changes the syntax of image inclusion in docs/src/ markdown files from html blocks to the markdown syntax, so that the DocumenterTypst.jl package can include the images correctly, and
• includes a commented-out line in docs/make.jl which builds the PDF through typst.

Using relative paths is necessary

This PR didn’t change image file paths. However, in future writing of the documentations, please note that absolute paths are not supported by DocumenterTypst.jl!

How to tune image width?

The markdown syntax does not control image width, so in some cases the output image can take up very much space, even the whole page, which you might not want. I'm not sure whether hard-wiring size information into the svg will work, and if all other methods don't work, one can still inspect the generated .typ file according to the docs of DocumenterTypst.jl and then modify image width.

To be specific, if we generate .typ output as instructed by the docs, the docs/build directory will be populated with 2 additional files: documenter.typ and TensorKit.typ where the former is a utility template helper, and the latter is a long file which #imports documenter.typ and can render to a PDF.

Using the typst previewer, the preview of TensorKit.typ can take a long time to load, and the preview itself is laggy. So instead of scrolling through the preview for images, one can simply search for image in TensorKit.typ (they are wrapped in #figure environments, so search for image instead of #image) and tune the width parameter to something other than the default 100%.

Possible dark-theme issue in html output

The statement class="color-invertible" will also be absent in the markdown syntax, causing vector graphics to no longer be inverted in dark themes. I've confirmed this behavior on my localhost. The html syntax is not supported by the typst backend currently.

To resolve this, it is indeed possible to dedicate a branch to the typst build, while the main branch is still the color-invertible-graphics html build, but that would mean you guys need to take care of both branches of the docs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
see 52 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.