mirror of
https://github.com/Myriad-Dreamin/tinymist.git
synced 2025-08-04 18:28:02 +00:00
docs: use theme-box to improve documentation diagrams (#1840)
* dev: use theme-box to improve documentation diagrams * feat: better fletcher * feat: set raw
This commit is contained in:
Myriad-Dreamin
GitHub
parent
4cd8c634d5
commit
dc4e43c5d8
6 changed files with 208 additions and 189 deletions
|
|
@ -13,19 +13,22 @@ typlite's goal is to convert docstrings in typst packages to LSP docs (Markdown
|
|||
|
||||
#let pg-node = node.with(corner-radius: 2pt, shape: "rect");
|
||||
#let out-format = box.with(width: 5em)
|
||||
#let typlite-convert-graph = diagram(
|
||||
node-stroke: 1pt,
|
||||
edge-stroke: 1pt,
|
||||
pg-node((0.5, 0), [Typst Source Code]),
|
||||
edge("-|>", link("https://typst.app/docs/reference/html/")[HTML Export]),
|
||||
pg-node((3, 0), [```xml <xml:typlite/>```]),
|
||||
edge("-|>"),
|
||||
pg-node((5, 0), out-format[LaTeX]),
|
||||
edge((3, 0), (5, -0.7), "-|>"),
|
||||
pg-node((5, -0.7), out-format[Markdown]),
|
||||
edge((3, 0), (5, 0.7), "-|>"),
|
||||
pg-node((5, 0.7), out-format[DocX]),
|
||||
)
|
||||
#let typlite-convert-graph(theme) = {
|
||||
let (colors, node, edge) = fletcher-ctx(theme)
|
||||
diagram(
|
||||
node-stroke: 1pt,
|
||||
edge-stroke: 1pt,
|
||||
pg-node((0.5, 0), [Typst Source Code]),
|
||||
edge("-|>", link("https://typst.app/docs/reference/html/")[HTML Export]),
|
||||
pg-node((3, 0), [```xml <xml:typlite/>```]),
|
||||
edge("-|>"),
|
||||
pg-node((5, 0), out-format[LaTeX]),
|
||||
edge((3, 0), (5, -0.7), "-|>"),
|
||||
pg-node((5, -0.7), out-format[Markdown]),
|
||||
edge((3, 0), (5, 0.7), "-|>"),
|
||||
pg-node((5, 0.7), out-format[DocX]),
|
||||
)
|
||||
}
|
||||
|
||||
#figure(
|
||||
cond-image(typlite-convert-graph),
|
||||
|
|
|
|||
|
|
@ -16,8 +16,8 @@ Let us take reading files from physical file system as example of processing com
|
|||
#let pg-vert-sep = 0.7
|
||||
#let pg-adjust = 18pt
|
||||
|
||||
#let sys-graph = move(
|
||||
dx: pg-adjust,
|
||||
#let sys-graph(theme) = {
|
||||
let (colors, node, edge) = fletcher-ctx(theme, node-shape: fletcher.shapes.rect)
|
||||
diagram(
|
||||
edge-stroke: 0.85pt,
|
||||
node-corner-radius: 3pt,
|
||||
|
|
@ -35,8 +35,7 @@ Let us take reading files from physical file system as example of processing com
|
|||
(0, -pg-vert-sep),
|
||||
"-}>",
|
||||
[didChange, \ didOpen, etc.],
|
||||
label-anchor: "center",
|
||||
label-pos: 0,
|
||||
label-pos: 0.27,
|
||||
),
|
||||
edge(
|
||||
(-0.8, pg-vert-sep),
|
||||
|
|
@ -44,7 +43,6 @@ Let us take reading files from physical file system as example of processing com
|
|||
(0, 0),
|
||||
"-}>",
|
||||
[readFile\ readDir, etc.],
|
||||
label-anchor: "center",
|
||||
label-pos: 0,
|
||||
),
|
||||
edge((-1, pg-vert-sep), (pg-hori-sep, pg-vert-sep), "-}>"),
|
||||
|
|
@ -64,30 +62,29 @@ Let us take reading files from physical file system as example of processing com
|
|||
(pg-hori-sep * 1.7, i * pg-vert-sep),
|
||||
"-}>",
|
||||
[source],
|
||||
label-pos: 1,
|
||||
label-pos: 0.7,
|
||||
)
|
||||
},
|
||||
node(
|
||||
(-1.3, 0),
|
||||
rotate(-90deg, rect(stroke: (bottom: (thickness: 1pt, dash: "dashed")), width: 120pt)[Input Sources]),
|
||||
rotate(-90deg, rect(
|
||||
stroke: (bottom: (paint: theme.main-color, thickness: 1pt, dash: "dashed")),
|
||||
width: 120pt,
|
||||
)[Input Sources]),
|
||||
stroke: none,
|
||||
),
|
||||
node(
|
||||
(pg-hori-sep + 1.45, 0),
|
||||
rotate(
|
||||
90deg,
|
||||
move(
|
||||
dy: pg-adjust * 2,
|
||||
rect(stroke: (bottom: (thickness: 1pt, dash: "dashed")), width: 120pt)[Compiler World],
|
||||
),
|
||||
),
|
||||
rotate(90deg, move(dy: pg-adjust * 2, rect(
|
||||
stroke: (bottom: (paint: theme.main-color, thickness: 1pt, dash: "dashed")),
|
||||
width: 120pt,
|
||||
)[Compiler World])),
|
||||
stroke: none,
|
||||
),
|
||||
),
|
||||
);
|
||||
)
|
||||
};
|
||||
|
||||
#figure(
|
||||
cond-image(sys-graph),
|
||||
caption: [The overlay virtual file system (VFS)],
|
||||
) <fig:overlay-vfs>
|
||||
#figure(cond-image(sys-graph), caption: [The overlay virtual file system (VFS)]) <fig:overlay-vfs>
|
||||
|
||||
The problem is to ensure that the compiler can read the content correctly from access models at the time.
|
||||
|
||||
|
|
|
|||
|
|
@ -26,7 +26,6 @@
|
|||
}
|
||||
#let md-alter(left, right) = left
|
||||
|
||||
#let colors = (blue.lighten(10%), olive, eastern)
|
||||
#import fletcher.shapes: diamond
|
||||
|
||||
#let fg-blue = main-color.mix(rgb("#0074d9"))
|
||||
|
|
@ -48,10 +47,28 @@
|
|||
}
|
||||
}
|
||||
|
||||
// todo: use theme-box, to solve theme issue of typst figures.
|
||||
#let cond-image(img) = context if shiroa-sys-target() == "html" {
|
||||
html.elem("div", attrs: ("class": "pseudo-image"), html.frame(img))
|
||||
theme-box(class: "pseudo-image", theme => {
|
||||
show raw.where(tab-size: 114): with-raw-theme.with(theme.style.code-theme)
|
||||
set text(fill: theme.main-color)
|
||||
set line(stroke: theme.main-color)
|
||||
html.frame(img(theme))
|
||||
})
|
||||
} else {
|
||||
align(center, img)
|
||||
theme-box(img)
|
||||
}
|
||||
|
||||
#let fletcher-ctx(theme, node-shape: fletcher.shapes.hexagon) = {
|
||||
(
|
||||
if theme.is-dark {
|
||||
(rgb("#66ccffa0"), rgb("#b0a4e3a0"), rgb("#a4e2c690"))
|
||||
} else {
|
||||
(rgb("#66ccffcf"), rgb("#b0a4e3cf"), rgb("#a4e2c690"))
|
||||
},
|
||||
node.with(shape: node-shape, stroke: theme.main-color),
|
||||
edge.with(stroke: theme.main-color),
|
||||
)
|
||||
}
|
||||
|
||||
#let note-box = pro-tip
|
||||
|
|
|
|||
|
|
@ -13,7 +13,6 @@ There are seven basic analyzers:
|
|||
- _signature resolver_ summarizes signature based on _definitions_ and _type check info_.
|
||||
- _call resolver_ check calls based on _signatures_ and _type check info_.
|
||||
|
||||
#let pg-node = node.with(corner-radius: 2pt, shape: "rect");
|
||||
#let ref-n = (0.6, 1);
|
||||
#let def-n = (1.9, 1);
|
||||
#let sig-n = (3.1, 1);
|
||||
|
|
@ -21,72 +20,69 @@ There are seven basic analyzers:
|
|||
#let expr-n = (2.2, 0);
|
||||
#let type-n = (3.3, 0);
|
||||
|
||||
#let ana-graph = diagram(
|
||||
node-stroke: 1pt,
|
||||
edge-stroke: 1pt,
|
||||
// edge("-|>", align(center)[Analysis\ Request], label-pos: 0.1),
|
||||
pg-node((0.3, 0.2), [`Lexical`\ `Hierarchy`]),
|
||||
edge("<|-", []),
|
||||
pg-node((1.2, 0), [`Source`]),
|
||||
edge("-|>", []),
|
||||
pg-node(expr-n, [`ExprInfo`]),
|
||||
edge("-|>"),
|
||||
pg-node(type-n, [`TypeInfo`]),
|
||||
edge("-|>"),
|
||||
pg-node(def-n, [`Definition`]),
|
||||
edge(expr-n, def-n, "-|>"),
|
||||
pg-node(ref-n, [`References`]),
|
||||
edge(def-n, ref-n, "-|>"),
|
||||
edge(expr-n, ref-n, "-|>"),
|
||||
pg-node(sig-n, [`Signature`]),
|
||||
edge(def-n, sig-n, "-|>"),
|
||||
edge(type-n, sig-n, "-|>"),
|
||||
pg-node(call-n, [`Call`]),
|
||||
edge(sig-n, call-n, "-|>"),
|
||||
edge(type-n, call-n, "-|>"),
|
||||
for i in range(9) {
|
||||
let j = 1 + i * 0.25
|
||||
edge((j, 1.4), (j, 1.8), "-|>")
|
||||
},
|
||||
pg-node(
|
||||
(2, 2.3),
|
||||
[`Extended`\
|
||||
`Language Features`],
|
||||
),
|
||||
// for i in (1, 3, 5) {
|
||||
// edge((i, 0), (i, -0.5), (5.5, -0.5), (5.6, 0), "-|>")
|
||||
// },
|
||||
// edge(
|
||||
// (0.3, 0.4),
|
||||
// (0.3, 0),
|
||||
// "-|>",
|
||||
// align(center)[clone #typst-func("Source")],
|
||||
// label-anchor: "center",
|
||||
// label-pos: -0.5,
|
||||
// ),
|
||||
// edge(
|
||||
// (2, 0.4),
|
||||
// (2, 0),
|
||||
// "-|>",
|
||||
// align(center)[snapshot ```rs trait World```],
|
||||
// label-anchor: "center",
|
||||
// label-pos: -0.5,
|
||||
// ),
|
||||
// edge(
|
||||
// (4, 0.4),
|
||||
// (4, 0),
|
||||
// "-|>",
|
||||
// align(center)[acquire #typst-func("Document")],
|
||||
// label-anchor: "center",
|
||||
// label-pos: -0.5,
|
||||
// ),
|
||||
);
|
||||
#let ana-graph(theme) = {
|
||||
let (colors, node, edge) = fletcher-ctx(theme, node-shape: "rect")
|
||||
diagram(
|
||||
node-stroke: 1pt,
|
||||
edge-stroke: 1pt,
|
||||
// edge("-|>", align(center)[Analysis\ Request], label-pos: 0.1),
|
||||
node((0.3, 0.2), [`Lexical`\ `Hierarchy`]),
|
||||
edge("<|-", []),
|
||||
node((1.2, 0), [`Source`]),
|
||||
edge("-|>", []),
|
||||
node(expr-n, [`ExprInfo`]),
|
||||
edge("-|>"),
|
||||
node(type-n, [`TypeInfo`]),
|
||||
edge("-|>"),
|
||||
node(def-n, [`Definition`]),
|
||||
edge(expr-n, def-n, "-|>"),
|
||||
node(ref-n, [`References`]),
|
||||
edge(def-n, ref-n, "-|>"),
|
||||
edge(expr-n, ref-n, "-|>"),
|
||||
node(sig-n, [`Signature`]),
|
||||
edge(def-n, sig-n, "-|>"),
|
||||
edge(type-n, sig-n, "-|>"),
|
||||
node(call-n, [`Call`]),
|
||||
edge(sig-n, call-n, "-|>"),
|
||||
edge(type-n, call-n, "-|>"),
|
||||
for i in range(9) {
|
||||
let j = 1 + i * 0.25
|
||||
edge((j, 1.4), (j, 1.8), "-|>")
|
||||
},
|
||||
node((2, 2.3), [`Extended`\
|
||||
`Language Features`]),
|
||||
// for i in (1, 3, 5) {
|
||||
// edge((i, 0), (i, -0.5), (5.5, -0.5), (5.6, 0), "-|>")
|
||||
// },
|
||||
// edge(
|
||||
// (0.3, 0.4),
|
||||
// (0.3, 0),
|
||||
// "-|>",
|
||||
// align(center)[clone #typst-func("Source")],
|
||||
// label-anchor: "center",
|
||||
// label-pos: -0.5,
|
||||
// ),
|
||||
// edge(
|
||||
// (2, 0.4),
|
||||
// (2, 0),
|
||||
// "-|>",
|
||||
// align(center)[snapshot ```rs trait World```],
|
||||
// label-anchor: "center",
|
||||
// label-pos: -0.5,
|
||||
// ),
|
||||
// edge(
|
||||
// (4, 0.4),
|
||||
// (4, 0),
|
||||
// "-|>",
|
||||
// align(center)[acquire #typst-func("Document")],
|
||||
// label-anchor: "center",
|
||||
// label-pos: -0.5,
|
||||
// ),
|
||||
)
|
||||
};
|
||||
|
||||
|
||||
#figure(
|
||||
cond-image(ana-graph),
|
||||
caption: [The relationship of analyzers.],
|
||||
) <fig:analyses-relationship>
|
||||
#figure(cond-image(ana-graph), caption: [The relationship of analyzers.]) <fig:analyses-relationship>
|
||||
|
||||
= Extending Language Features
|
||||
|
||||
|
|
|
|||
|
|
@ -12,28 +12,28 @@ The each actor holds and maintains some resources exclusively. For example, the
|
|||
|
||||
The actors communicate with each other by channels. An actor should own many receivers as its input, and many senders as output. The actor will take input from receivers _sequentially_. For example, when some LSP request or notification is coming as an LSP event, multiple actors serve the event collaboratively, as shown in @fig:actor-serve-lsp-requests.
|
||||
|
||||
#let actor-graph = diagram(
|
||||
edge-stroke: 0.85pt,
|
||||
node-corner-radius: 3pt,
|
||||
edge-corner-radius: 4pt,
|
||||
mark-scale: 80%,
|
||||
node((0, 0), [LSP Requests/\ Notifications\ (Channel)], fill: colors.at(0), shape: fletcher.shapes.hexagon),
|
||||
node((2, +1), [RenderActor], fill: colors.at(1)),
|
||||
node((2, 0), align(center)[`CompileServerActor`], fill: colors.at(1)),
|
||||
node((2, -1), [`LspActor` (Main Thread)], fill: colors.at(1)),
|
||||
node((4, 0), [LSP Responses\ (Channel)], fill: colors.at(2), shape: fletcher.shapes.hexagon),
|
||||
edge((0, 0), "r,u,r", "-}>"),
|
||||
edge((2, -1), "r,d,r", "-}>"),
|
||||
edge((2, 0), "rr", "-}>"),
|
||||
edge((2, 1), "r,u,r", "-}>"),
|
||||
edge((2, 0), (2, 1), align(center)[Rendering\ Requests], "-}>"),
|
||||
edge((2, -1), (2, 0), align(center)[Analysis\ Requests], "-}>"),
|
||||
)
|
||||
#let actor-graph(theme) = {
|
||||
let (colors, node, edge) = fletcher-ctx(theme)
|
||||
diagram(
|
||||
edge-stroke: 0.85pt,
|
||||
node-corner-radius: 3pt,
|
||||
edge-corner-radius: 4pt,
|
||||
mark-scale: 80%,
|
||||
node((0, 0), [LSP Requests/\ Notifications\ (Channel)], fill: colors.at(0), shape: fletcher.shapes.hexagon),
|
||||
node((2, +1), [RenderActor], fill: colors.at(1)),
|
||||
node((2, 0), align(center)[`CompileServerActor`], fill: colors.at(1)),
|
||||
node((2, -1), [`LspActor` (Main Thread)], fill: colors.at(1)),
|
||||
node((4, 0), [LSP Responses\ (Channel)], fill: colors.at(2), shape: fletcher.shapes.hexagon),
|
||||
edge((0, 0), "r,u,r", "-}>"),
|
||||
edge((2, -1), "r,d,r", "-}>"),
|
||||
edge((2, 0), "rr", "-}>"),
|
||||
edge((2, 1), "r,u,r", "-}>"),
|
||||
edge((2, 0), (2, 1), align(center)[Rendering\ Requests], "-}>"),
|
||||
edge((2, -1), (2, 0), align(center)[Analysis\ Requests], "-}>"),
|
||||
)
|
||||
}
|
||||
|
||||
#figure(
|
||||
cond-image(actor-graph),
|
||||
caption: [The IO Graph of actors serving a LSP request or notification],
|
||||
) <fig:actor-serve-lsp-requests>
|
||||
#figure(cond-image(actor-graph), caption: [The IO Graph of actors serving a LSP request or notification]) <fig:actor-serve-lsp-requests>
|
||||
|
||||
A _Hover_ request is taken as example of that events.
|
||||
|
||||
|
|
@ -52,50 +52,49 @@ he most critical features are lsp functions, built on the #github-link("/crates/
|
|||
|
||||
When an analysis request is coming, tinymist _upgrades_ it to a suitable level as needed, as shown in @fig:analysis-upgrading-level. A higher level requires to hold more resources and takes longer time to prepare.
|
||||
|
||||
#let pg-node = node.with(corner-radius: 2pt, shape: "rect");
|
||||
#let ana-level-graph = diagram(
|
||||
node-stroke: 1pt,
|
||||
edge-stroke: 1pt,
|
||||
edge("-|>", align(center)[Analysis\ Request], label-pos: 0.1),
|
||||
pg-node((1, 0), [Syntax\ Level]),
|
||||
edge("-|>", []),
|
||||
pg-node((3, 0), [Semantic\ Level]),
|
||||
edge("-|>"),
|
||||
pg-node((5, 0), [Stateful\ Level]),
|
||||
edge((5, 0), (6, 0), "-|>", align(center)[Analysis\ Response], label-pos: 1),
|
||||
for i in (1, 3, 5) {
|
||||
edge((i, 0), (i, -0.5), (5.5, -0.5), (5.6, 0), "-|>")
|
||||
},
|
||||
edge(
|
||||
(0.3, 0.4),
|
||||
(0.3, 0),
|
||||
"-|>",
|
||||
align(center)[clone #typst-func("Source")],
|
||||
label-anchor: "center",
|
||||
label-pos: -0.5,
|
||||
),
|
||||
edge(
|
||||
(2, 0.4),
|
||||
(2, 0),
|
||||
"-|>",
|
||||
align(center)[snapshot ```rs trait World```],
|
||||
label-anchor: "center",
|
||||
label-pos: -0.5,
|
||||
),
|
||||
edge(
|
||||
(4, 0.4),
|
||||
(4, 0),
|
||||
"-|>",
|
||||
align(center)[acquire #typst-func("Document")],
|
||||
label-anchor: "center",
|
||||
label-pos: -0.5,
|
||||
),
|
||||
)
|
||||
#let ana-level-graph(theme) = {
|
||||
let (colors, node, edge) = fletcher-ctx(theme, node-shape: fletcher.shapes.rect)
|
||||
diagram(
|
||||
node-stroke: 1pt,
|
||||
edge-stroke: 1pt,
|
||||
edge("-|>", align(center)[Analysis\ Request], label-pos: 0.1),
|
||||
node((1, 0), [Syntax\ Level]),
|
||||
edge("-|>", []),
|
||||
node((3, 0), [Semantic\ Level]),
|
||||
edge("-|>"),
|
||||
node((5, 0), [Stateful\ Level]),
|
||||
edge((5, 0), (6, 0), "-|>", align(center)[Analysis\ Response], label-pos: 1),
|
||||
for i in (1, 3, 5) {
|
||||
edge((i, 0), (i, -0.5), (5.5, -0.5), (5.6, 0), "-|>")
|
||||
},
|
||||
edge(
|
||||
(0.3, 0.4),
|
||||
(0.3, 0),
|
||||
"-|>",
|
||||
align(center)[clone #typst-func("Source")],
|
||||
label-anchor: "center",
|
||||
label-pos: -0.5,
|
||||
),
|
||||
edge(
|
||||
(2, 0.4),
|
||||
(2, 0),
|
||||
"-|>",
|
||||
align(center)[snapshot ```rs trait World```],
|
||||
label-anchor: "center",
|
||||
label-pos: -0.5,
|
||||
),
|
||||
edge(
|
||||
(4, 0.4),
|
||||
(4, 0),
|
||||
"-|>",
|
||||
align(center)[acquire #typst-func("Document")],
|
||||
label-anchor: "center",
|
||||
label-pos: -0.5,
|
||||
),
|
||||
)
|
||||
}
|
||||
|
||||
#figure(
|
||||
cond-image(ana-level-graph),
|
||||
caption: [The analyzer upgrades the level to acquire necessary resources],
|
||||
) <fig:analysis-upgrading-level>
|
||||
#figure(cond-image(ana-level-graph), caption: [The analyzer upgrades the level to acquire necessary resources]) <fig:analysis-upgrading-level>
|
||||
|
||||
= Optional Non-LSP Features
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue