Feat/cheat sheet

[cvanelteren]

WIP for a MPL style cheat sheet. The icons are added to the docs to give a similar type overview as mpl has. May need to move the cheat sheet out of this repo.

[munechika-koyo]

Nice to use Typst-written cheat sheets!
Do you have a link to built PDF cheat sheets somewhere, like matplotlib?

[cvanelteren]

Not yet but also not happy yet with how it looks yet. I love typ wish it would replace tex already.

[munechika-koyo]

Not yet but also not happy yet with how it looks yet. I love typ wish it would replace tex already.

Yeah, I want more journal publishers to adopt Typst. They still seem to stick to using TeX as source files.

[cvanelteren]

@munechika-koyo

thisi is a better direction I think

[cvanelteren]

bit more tweaking later:

[cvanelteren]

CC @gepcel

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[munechika-koyo]

Thanks for iterating on this. I think the latest direction is much clearer, but I still find the sheet somewhat difficult to scan quickly as a cheat sheet.

The main issue for me is not the amount of information itself, but that many items have similar visual weight, so it takes a while to locate the API I want.

I made a rough layout mockup to illustrate the kind of information hierarchy I have in mind. This is not intended as a finished design or a request to reproduce it exactly; it is mainly meant to show the direction of the suggested reorganization.

The main changes I would suggest are:

• make code and body text larger, even if that requires reducing the number of examples on a single sheet;
• split the current large “Subplots, labels & annotations” gallery into smaller, task-oriented groups;
• for comparisons such as share=False, share='limits', and share='all', emphasize the semantic difference rather than showing several very small plots;
• use a consistent visual pattern such as result → key argument → minimal code for feature cards;
• group the plot gallery by purpose, e.g. distribution, network/flow, polar/diagnostics, variants, etc.;
• use the section colors as navigation/category cues rather than mostly as decoration;
• keep a small “start here” area for the most frequently used APIs such as uplt.subplots() and axs.format().

Another possibility is to avoid trying to fit everything onto a single sheet and instead provide multiple sheets for different experience levels, similar to the way Matplotlib provides separate beginner/intermediate material.

For example:

• Beginner

  • basic plotting
  • uplt.subplots()
  • axs.format()
  • labels and titles
  • basic legends
  • basic colorbars

• Intermediate

  • advanced subplot layouts
  • axis sharing
  • spanning labels
  • panels and inset axes
  • secondary/dual axes
  • colormap handling
  • more advanced guide placement

• Advanced

  • specialized legends
  • geographic plotting
  • specialist plot types
  • advanced layout controls
  • less frequently used APIs

Splitting the material this way could solve two problems at once: it would allow larger, more readable examples while still preserving the breadth of UltraPlot's API. It would also give new users a much clearer entry point while keeping the more specialized features discoverable.

My goal would be that a user can find the relevant feature/API in roughly a couple of seconds, rather than needing to read through most of the sheet.

Would you be open to revisiting the layout in drawio.py / the editable draw.io sheet along these lines?

(Mockup attached below; it is intentionally incomplete and schematic, and mainly illustrates the information hierarchy rather than the exact final design.)

[cvanelteren]

Not a bad idea. I can will do a little drawing sesh to iterate in these ideas.

[cvanelteren]

[cvanelteren]

Note these had to be downsampled as the originals aree 50+ mb

[cvanelteren]

Forgot the beginner one -- hold on

[cvanelteren]

[cvanelteren]

Ok so my approach still needs drawio, will need to figure out if I can just read the svg directly from the xml file

[munechika-koyo]

Really looks good!
One small point: Can you align the parameter header? e.g. for the case of the second box on the left:

ax.format(
    title=...,
    abc=...,
    abcloc=...,
    xlabel=...,
    ylabel=...,
)

I don't think it's necessary to go so far as to mess up the layout, though.

[cvanelteren]

Need to fix the loading issue as it is rather slow due to the size of the images