Merge pull request #1485 from Myriad-Dreamin/pdf-documentation

feat: generate documentation in PDF format
Myriad-Dreamin · Mar 11, 2025 · d944240 · d944240
2 parents 5a038c9 + 288243c
commit d944240
Show file tree

Hide file tree

Showing 37 changed files with 183 additions and 50 deletions.
diff --git a/.github/workflows/gh_pages.yml b/.github/workflows/gh_pages.yml
@@ -49,9 +49,7 @@ jobs:
           curl -L https://github.com/Myriad-Dreamin/shiroa/releases/download/v0.1.5/source-han-serif-font-assets.tar.gz | tar -xvz -C assets/fonts
       - name: Download & install shiroa
         run: |
-          curl -L https://github.com/Myriad-Dreamin/shiroa/releases/download/v0.2.0-nightly5/shiroa-x86_64-unknown-linux-gnu.tar.gz | tar -xvz
-          chmod +x shiroa-x86_64-unknown-linux-gnu/bin/shiroa
-          sudo cp shiroa-x86_64-unknown-linux-gnu/bin/shiroa /usr/bin/shiroa
+          curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Myriad-Dreamin/shiroa/releases/download/v0.3.0/shiroa-installer.sh | sh
       - name: Install Node.js
         uses: actions/setup-node@v4
         with:

diff --git a/.github/workflows/release-vscode.yml b/.github/workflows/release-vscode.yml
@@ -198,6 +198,21 @@ jobs:
         run: |
           cargo build --profile=gh-release -p tinymist --target ${{ matrix.rust-target }}
         if: startsWith(github.ref, 'refs/tags/') || matrix.regular_build == 'true'
+      # todo: pdf documentation for all platforms
+      - name: Build PDF Documentation
+        run: |
+          cargo run --profile=gh-release -p tinymist --target ${{ matrix.rust-target }} -- compile --font-path assets/fonts --root . docs/tinymist/ebook.typ
+          cp docs/tinymist/ebook.pdf tinymist-docs.pdf
+          mkdir -p contrib/html/editors/vscode/out/ editors/vscode/out/
+          cp tinymist-docs.pdf editors/vscode/out/tinymist-docs.pdf
+          cp tinymist-docs.pdf contrib/html/editors/vscode/out/tinymist-docs.pdf
+        if: matrix.rust-target == 'x86_64-unknown-linux-gnu' && (fromJson(env.isRelease) || fromJson(env.isNightly))
+      - name: Upload PDF Documentation
+        if: matrix.rust-target == 'x86_64-unknown-linux-gnu' && (fromJson(env.isRelease) || fromJson(env.isNightly))
+        uses: actions/upload-artifact@v4
+        with:
+          name: tinymist-docs.pdf
+          path: tinymist-docs.pdf
       - name: Rename debug symbols for windows
         if: matrix.platform == 'win32' && (fromJson(env.isRelease) || fromJson(env.isNightly))
         run: |

diff --git a/.gitignore b/.gitignore
@@ -10,4 +10,5 @@ editors/lapce/out/
 /external/typst-preview
 /dist
 
+*.pdf
 .vscode/*.code-workspace
diff --git a/LICENSE b/LICENSE
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2023 Myriad Dreamin, Nathan Varner
+   Copyright 2023-2025 Myriad Dreamin, Nathan Varner
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

diff --git a/contrib/html/editors/vscode/.vscodeignore b/contrib/html/editors/vscode/.vscodeignore
@@ -1,4 +1,5 @@
 **
+!out/tinymist-docs.pdf
 !out/extension.js
 !out/extension.web.js
 !out/server.js

diff --git a/contrib/html/editors/vscode/LICENSE b/contrib/html/editors/vscode/LICENSE
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2023 Myriad Dreamin, Nathan Varner
+   Copyright 2023-2025 Myriad Dreamin, Nathan Varner
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

diff --git a/docs/tinymist/book.typ b/docs/tinymist/book.typ
@@ -1,5 +1,5 @@
 
-#import "@preview/shiroa:0.1.2": *
+#import "@preview/shiroa:0.2.0": *
 
 #show: book
 
@@ -22,8 +22,8 @@
       - #chapter("frontend/zed.typ")[Zed]
     = Features
     - #chapter("feature/cli.typ")[Command line interface]
-    - #chapter("feature/docs.typ")[Documentation]
-    - #chapter("guide/completion.typ")[Completion]
+    - #chapter("feature/docs.typ")[Code Documentation]
+    - #chapter("guide/completion.typ")[Code Completion]
     - #chapter("feature/export.typ")[Exporting Documents]
     - #chapter("feature/preview.typ")[Document Preview]
     - #chapter("feature/language.typ")[Other Features]

diff --git a/docs/tinymist/commands.typ b/docs/tinymist/commands.typ
@@ -1,6 +1,6 @@
 #import "mod.typ": *
 
-#show: book-page.with(title: "Tinymist Command System")
+#show: book-page.with(title: [Command System])
 
 The extra features are exposed via LSP's #link("https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_executeCommand")[`workspace/executeCommand`] request, forming a command system. The commands in the system share a name convention.
 

diff --git a/docs/tinymist/configurations.typ b/docs/tinymist/configurations.typ
@@ -1,7 +1,7 @@
 #import "mod.typ": *
 #import "@preview/cmarker:0.1.0": render as md
 
-#show: book-page.with(title: "Tinymist Configurations")
+#show: book-page.with(title: [Configurations])
 
 #let packages = json("/editors/vscode/package.json")
 

diff --git a/docs/tinymist/crate-docs.typ b/docs/tinymist/crate-docs.typ
@@ -2,4 +2,4 @@
 
 #show: book-page.with(title: "Crate Docs")
 
-#cross-link("/rs/tinymist/index.typ")[Tinymist Crate Docs (for Developers)]
+#link("https://myriad-dreamin.github.io/tinymist/rs/tinymist/index.html")[Tinymist Crate Docs (for Developers)]
diff --git a/docs/tinymist/ebook.typ b/docs/tinymist/ebook.typ
@@ -1,8 +1,10 @@
-#import "@preview/shiroa:0.1.2": *
+#import "@preview/shiroa:0.2.0": *
 
 #import "/typ/templates/ebook.typ"
 
-#show: ebook.project.with(title: "tinymist", spec: "book.typ")
+#import "/typ/templates/tinymist-version.typ": tinymist-package
+
+#show: ebook.project.with(title: [Tinymist Documentation (v#tinymist-package.version)], spec: "book.typ")
 
 // set a resolver for inclusion
 #ebook.resolve-inclusion(it => include it)
diff --git a/docs/tinymist/feature/cli.typ b/docs/tinymist/feature/cli.typ
@@ -1,6 +1,6 @@
 #import "mod.typ": *
 
-#show: book-page.with(title: "Tinymist Command Line Interface (CLI)")
+#show: book-page.with(title: [Command Line Interface (CLI)])
 
 == Starting a Language Server
 

diff --git a/docs/tinymist/feature/docs.typ b/docs/tinymist/feature/docs.typ
@@ -1,6 +1,6 @@
 #import "mod.typ": *
 
-#show: book-page.with(title: "Documentation")
+#show: book-page.with(title: [Code Documentation])
 
 Tinymist will read the documentation from the source code and display it in the editor. For example, you can hover over a identifier to see its documentation, usually the content of the comments above the identifier's definition. The format of the documentation follows #link("https://github.com/typst-community/guidelines/pull/8")[this guideline].
 

diff --git a/docs/tinymist/feature/language.typ b/docs/tinymist/feature/language.typ
@@ -1,5 +1,5 @@
 #import "mod.typ": *
 
-#show: book-page.with(title: "Tinymist Language and Editor Features")
+#show: book-page.with(title: [Language and Editor Features])
 
 #include "language-content.typ"
diff --git a/docs/tinymist/feature/preview.typ b/docs/tinymist/feature/preview.typ
@@ -1,6 +1,6 @@
 #import "mod.typ": *
 
-#show: book-page.with(title: "Tinymist Preview Feature")
+#show: book-page.with(title: [Preview Feature])
 
 Two ways of previewing a Typst document are provided:
 - PDF Preview: let lsp export your PDF on typed, and open related PDF by your favorite PDF viewer.

diff --git a/docs/tinymist/frontend/emacs.typ b/docs/tinymist/frontend/emacs.typ
@@ -1,6 +1,6 @@
 #import "/docs/tinymist/frontend/mod.typ": *
 
-#show: book-page.with(title: "Tinymist Emacs Extension")
+#show: book-page.with(title: [Emacs])
 
 Run and configure tinymist in Emacs for Typst.
 

diff --git a/docs/tinymist/frontend/helix.typ b/docs/tinymist/frontend/helix.typ
@@ -1,6 +1,6 @@
 #import "/docs/tinymist/frontend/mod.typ": *
 
-#show: book-page.with(title: "Tinymist Helix Extension")
+#show: book-page.with(title: [Helix])
 
 Run and configure tinymist in helix for Typst.
 

diff --git a/docs/tinymist/frontend/main.typ b/docs/tinymist/frontend/main.typ
@@ -1,6 +1,6 @@
 #import "mod.typ": *
 
-#show: book-page.with(title: "Tinymist Editor Frontends")
+#show: book-page.with(title: [Editor Frontends])
 
 Leveraging the interface of LSP, tinymist provides frontends to each editor, located in the #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors")[editor folders]. They are minimal, meaning that LSP should finish its main LSP features as many as possible without help of editor frontends. The editor frontends just enhances your code experience. For example, the vscode frontend takes responsibility on providing some nice editor tools. It is recommended to install these editors frontend for your editors.
 

diff --git a/docs/tinymist/frontend/neovim.typ b/docs/tinymist/frontend/neovim.typ
@@ -1,6 +1,6 @@
 #import "/docs/tinymist/frontend/mod.typ": *
 
-#show: book-page.with(title: "Tinymist Neovim Extension")
+#show: book-page.with(title: [Neovim])
 
 Run and configure `tinymist` in Neovim with support for all major distros and package managers.
 

diff --git a/docs/tinymist/frontend/sublime-text.typ b/docs/tinymist/frontend/sublime-text.typ
@@ -1,7 +1,7 @@
 
 #import "/docs/tinymist/frontend/mod.typ": *
 
-#show: book-page.with(title: "Tinymist Sublime Support for Typst")
+#show: book-page.with(title: [Sublime Support])
 
 Follow the instructions in the #link("https://github.com/sublimelsp/LSP/blob/main/docs/src/language_servers.md#tinymist")[sublimelsp documentation] to make it work.
 

diff --git a/docs/tinymist/frontend/vscode.typ b/docs/tinymist/frontend/vscode.typ
@@ -1,6 +1,6 @@
 #import "/docs/tinymist/frontend/mod.typ": *
 
-#show: book-page.with(title: "Tinymist VS Code Extension")
+#show: book-page.with(title: [VS Cod(e,ium)])
 
 A VS Code or VS Codium extension for Typst. You can find the extension on:
 

diff --git a/docs/tinymist/frontend/zed.typ b/docs/tinymist/frontend/zed.typ
@@ -1,6 +1,6 @@
 #import "/docs/tinymist/frontend/mod.typ": *
 
-#show: book-page.with(title: "Tinymist Zed Extension")
+#show: book-page.with(title: [Zed])
 
 See #link("https://github.com/WeetHet/typst.zed")[typst.zed];.
 

diff --git a/docs/tinymist/guide/completion.typ b/docs/tinymist/guide/completion.typ
@@ -1,6 +1,6 @@
 #import "mod.typ": *
 
-#show: book-page.with(title: "Guide: Completion")
+#show: book-page.with(title: [Code Completion])
 
 == Using LSP-Based Completion
 

diff --git a/docs/tinymist/inputs.typ b/docs/tinymist/inputs.typ
@@ -1,6 +1,6 @@
 #import "mod.typ": *
 
-#show: book-page.with(title: "Tinymist LSP Inputs")
+#show: book-page.with(title: [LSP Inputs])
 
 == Prefer to Using LSP Configurations
 

diff --git a/docs/tinymist/mod.typ b/docs/tinymist/mod.typ
@@ -1,7 +1,7 @@
 
 #import "/docs/tinymist/book.typ": book-page, cross-link
 #import "/typ/templates/page.typ": *
-#import "@preview/fletcher:0.4.4" as fletcher: *
+#import "@preview/fletcher:0.5.6" as fletcher: *
 #import "@preview/numbly:0.1.0": numbly
 
 /// This function is to render a text string in monospace style and function

diff --git a/docs/tinymist/module/lsp.typ b/docs/tinymist/module/lsp.typ
@@ -1,6 +1,6 @@
 #import "mod.typ": *
 
-#show: book-page.with(title: "Tinymist LSP")
+#show: book-page.with(title: [LSP])
 
 == Architecture
 

diff --git a/docs/tinymist/module/preview.typ b/docs/tinymist/module/preview.typ
@@ -1,6 +1,6 @@
 #import "mod.typ": *
 
-#show: book-page.with(title: "Tinymist Preview")
+#show: book-page.with(title: [Preview])
 
 Todo: rewrite this guide #link("https://enter-tainer.github.io/typst-preview/arch.html")[Developer Guide: Typst-Preview Architecture].
 

diff --git a/docs/tinymist/module/query.typ b/docs/tinymist/module/query.typ
@@ -1,6 +1,6 @@
 #import "mod.typ": *
 
-#show: book-page.with(title: "Tinymist Language Queries")
+#show: book-page.with(title: [Language Queries])
 
 == Base Analyses
 
@@ -47,11 +47,14 @@ There are seven basic analyzers:
       edge(sig-n, call-n, "-|>"),
       edge(type-n, call-n, "-|>"),
       for i in range(9) {
-        let j = 1 + i * 0.25;
+        let j = 1 + i * 0.25
         edge((j, 1.4), (j, 1.8), "-|>")
       },
-      pg-node((2, 2.3), [`Extended`\
-      `Language Features`]),
+      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), "-|>")
       // },

diff --git a/docs/tinymist/principles.typ b/docs/tinymist/principles.typ
@@ -1,6 +1,6 @@
 #import "mod.typ": *
 
-#show: book-page.with(title: "Tinymist Principles")
+#show: book-page.with(title: [Principles])
 
 Four principles are followed.
 

diff --git a/docs/tinymist/type-system.typ b/docs/tinymist/type-system.typ
@@ -1,6 +1,6 @@
 #import "mod.typ": *
 
-#show: book-page.with(title: "Tinymist Type System")
+#show: book-page.with(title: [Type System])
 
 The underlying techniques are not easy to understand, but there are some links:
 - bidirectional type checking: https://jaked.org/blog/2021-09-15-Reconstructing-TypeScript-part-1
@@ -25,10 +25,10 @@ Second, the $sig$ and the $sans("argument")$ type are reused frequently.
   - an optional rest argument, in $sans("arr")$ type.
   - an *optional* body, in any type.
 
-  notated as $sig := sig(sans("tup")(tau_1,..,tau_n),sans("rec")(a_1=tau_(n+1),..,a_m=tau_(n+m)),..sans("arr")(tau_(n+m+1))) arrow psi$
+  notated as $sig := sig\(sans("tup")(tau_1,..,tau_n),sans("rec")(a_1=tau_(n+1),..,a_m=tau_(n+m)),\.\.sans("arr");(tau_(n+m+1))) arrow psi$
 - the $sans("argument")$ is a $sans("signature")$ without rest and body.
 
-  $args := args(sig(..))$
+  $args := args\(sig\(..))$
 
 With aboving constructors, we soonly get typst's type checker.
 

diff --git a/editors/vscode/.vscodeignore b/editors/vscode/.vscodeignore
@@ -1,4 +1,5 @@
 **
+!out/tinymist-docs.pdf
 !out/extension.js
 !out/extension.web.js
 !out/tinymist

diff --git a/editors/vscode/LICENSE b/editors/vscode/LICENSE
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2023 Myriad Dreamin, Nathan Varner
+   Copyright 2023-2025 Myriad Dreamin, Nathan Varner
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

diff --git a/package.json b/package.json
@@ -18,6 +18,7 @@
     "build:preview": "cd tools/typst-preview-frontend && yarn run build && rimraf ../../crates/tinymist-assets/src/typst-preview.html && cpr ./dist/index.html ../../crates/tinymist-assets/src/typst-preview.html",
     "maintainers": "typst query MAINTAINERS.typ \"<maintainer-meta>\" --pretty --one --field value --input=action=help",
     "docs": "shiroa serve --font-path assets/fonts -w . docs/tinymist",
+    "docs:pdf": "cargo run --bin tinymist --release -- compile --font-path assets/fonts --root . docs/tinymist/ebook.typ",
     "docs:typ": "node scripts/link-docs.mjs",
     "docs:rs": "cargo doc --workspace --document-private-items --no-deps",
     "lint": "eslint editors/vscode/src",
-Original file line number
+Diff line change
@@ Expand Up / @@ -10,4 +10,5 @@ editors/lapce/out/ @@
     /external/typst-preview
     /dist
+    *.pdf
     .vscode/*.code-workspace
Original file line number	Diff line number	Diff line change
Expand Up		@@ -2,4 +2,4 @@

		#show: book-page.with(title: "Crate Docs")

		#cross-link("/rs/tinymist/index.typ")[Tinymist Crate Docs (for Developers)]
		#link("https://myriad-dreamin.github.io/tinymist/rs/tinymist/index.html")[Tinymist Crate Docs (for Developers)]