Skip to content

Commit 9eaa975

Browse files
CXPhoenixCXPhoenix
committed
✨ feat: 新增 npm 發布工作流程、完整繁體中文 README 及 stdin 輸入功能
 🚀 新增 GitHub Actions 自動發布至 npm registry 工作流程 📖 完整重寫 README.md 為繁體中文版本，增加詳細功能說明 ⌨️ 新增多種 stdin 輸入處理方式（預定義、註解、互動模式） 🔄 更新套件資訊和依賴版本 📋 新增功能特色說明、進階設定和開發指南
1 parent 16e28d2 commit 9eaa975

6 files changed

Lines changed: 2405 additions & 2561 deletions

File tree

‎.github/workflows/publish-npm.yaml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
name: Release to NPM
2+
3+
on:
4+
release:
5+
types: [published]
6+
7+
jobs:
8+
release:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- name: Checkout 🛎️
12+
uses: actions/checkout@v4
13+
14+
- name: Setup Node.js
15+
uses: actions/setup-node@v4
16+
with:
17+
node-version: lts/*
18+
registry-url: https://registry.npmjs.org
19+
scope: "@cxphoenix"
20+
21+
- name: Install PNPM
22+
run: npm install -g pnpm@10.5.2
23+
24+
- name: Install dependencies 📦️
25+
run: pnpm install --frozen-lockfile
26+
27+
- name: Build 🔨
28+
run: pnpm build
29+
30+
# 從 GitHub Release 獲取版本號並更新 package.json
31+
- name: Update version from GitHub Release
32+
run: |
33+
VERSION=${GITHUB_REF#refs/tags/v}
34+
# 使用 jq 更新 package.json 中的版本號
35+
jq ".version = \"$VERSION\"" package.json > temp.json && mv temp.json package.json
36+
echo "Publishing version: $VERSION"
37+
38+
- name: Publish to NPM 📦
39+
run: pnpm publish --no-git-checks --access public
40+
env:
41+
NODE_AUTH_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}

‎README.md‎

Lines changed: 163 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,205 @@
11
# slidev-addon-python-runner
22

3-
Python runner for the [Monaco Runner feature](https://sli.dev/features/monaco-run) in [Slidev](https://sli.dev/). Code executed in browser using [Pyodide](https://pyodide.org/).
3+
[![npm version](https://badge.fury.io/js/%40cxphoenix%2Fslidev-addon-python-runner.svg)](https://badge.fury.io/js/%40cxphoenix%2Fslidev-addon-python-runner)
4+
[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/CXPhoenix/slidev-addon-python-runner/blob/main/LICENSE)
5+
[![Slidev](https://img.shields.io/badge/slidev-addon-brightgreen.svg)](https://sli.dev/addons/)
6+
[![Pyodide](https://img.shields.io/badge/powered%20by-Pyodide-orange.svg)](https://pyodide.org/)
7+
8+
為 [Slidev](https://sli.dev/) 中的 [Monaco Runner 功能](https://sli.dev/features/monaco-run) 提供的 Python 執行器。程式碼使用 [Pyodide](https://pyodide.org/) 在瀏覽器中執行。
49

510
![Demo](https://cdn.jsdelivr.net/gh/KermanX/slidev-addon-python-runner/assets/demo.png)
611

7-
## Usage
12+
## 功能特色
13+
14+
- 🐍 在瀏覽器中執行 Python 程式碼
15+
- 📦 支援從 PyPI 安裝套件
16+
- ⚡ 自動載入匯入的內建套件
17+
- 🔄 支援 stdin 輸入處理
18+
- 🎨 支援 `py` 和 `python` 兩種語言識別碼
19+
- 🛠️ 豐富的錯誤提示和除錯功能
20+
21+
## 使用方法
822

9-
Firstly, install the package:
23+
首先，安裝套件：
1024

1125
```bash
12-
npm install slidev-addon-python-runner
26+
npm install @cxphoenix/slidev-addon-python-runner
1327
```
1428

15-
Then, add it as an addon in your headmatter in `slides.md`:
29+
然後，在 `slides.md` 檔案的 headmatter 中加入該 addon：
1630

1731
```md
1832
---
1933
addons:
2034
- slidev-addon-python-runner
2135

22-
# Optional configuration for this runner
36+
# 此執行器的可選設定
2337
python:
24-
# Install packages from PyPI. Default: []
25-
installs: ["cowsay"]
38+
# 從 PyPI 安裝套件。預設值：[]
39+
installs: ["cowsay", "numpy", "pandas"]
2640

27-
# Code executed to set up the environment. Default: ""
41+
# 用於設置環境的程式碼。預設值：""
2842
prelude: |
2943
GREETING_FROM_PRELUDE = "Hello, Slidev!"
3044

31-
# Automatically load the imported builtin packages. Default: true
45+
# 自動載入已匯入的內建套件。預設值：true
3246
loadPackagesFromImports: true
3347

34-
# Disable annoying warning from `pandas`. Default: true
48+
# 停用 `pandas` 的煩人警告。預設值：true
3549
suppressDeprecationWarnings: true
3650

37-
# Always reload the Python environment when the code changes. Default: false
51+
# 程式碼變更時總是重新載入 Python 環境。預設值：false
3852
alwaysReload: false
3953

40-
# Options passed to `loadPyodide`. Default: {}
54+
# 傳遞給 `loadPyodide` 的選項。預設值：{}
4155
loadPyodideOptions: {}
56+
57+
# stdin 輸入設定（可選）
58+
stdin: ["input1", "input2"] # 預定義輸入陣列
59+
# 或者使用多行字串：
60+
# stdin: |
61+
# first line
62+
# second line
63+
# 或者啟用互動模式：
64+
# stdin: "interactive"
4265
---
4366
```
4467

45-
To add an interactive Python code runner, use the `monaco-run` directive:
68+
### 基本範例
69+
70+
若要新增互動式 Python 程式碼執行器，請使用 `monaco-run` 指令：
4671

4772
````md
4873
```py {monaco-run}
4974
from termcolor import colored
75+
import pandas as pd
76+
import numpy as np
5077

5178
print(colored("Hello, Slidev!", "blue"))
79+
80+
# 建立簡單的 DataFrame
81+
df = pd.DataFrame({
82+
"A": [1, 2, 3, 4],
83+
"B": np.random.randn(4)
84+
})
85+
print(df)
86+
```
87+
````
88+
89+
### stdin 輸入處理
90+
91+
這個 addon 支援多種方式處理 stdin 輸入：
92+
93+
#### 方法 1：在 frontmatter 中預定義輸入
94+
95+
````md
96+
---
97+
python:
98+
stdin:
99+
- "Alice"
100+
- "25"
101+
---
102+
103+
```py {monaco-run}
104+
name = input("請輸入姓名: ")
105+
age = input("請輸入年齡: ")
106+
print(f"你好 {name}，你今年 {age} 歲")
107+
```
108+
````
109+
110+
#### 方法 2：使用程式碼註解定義輸入
111+
112+
````md
113+
```py {monaco-run}
114+
# stdin: "Bob"
115+
# stdin: "30"
116+
name = input("請輸入姓名: ")
117+
age = input("請輸入年齡: ")
118+
print(f"你好 {name}，你今年 {age} 歲")
119+
```
120+
````
121+
122+
#### 方法 3：啟用互動模式
123+
124+
````md
125+
---
126+
python:
127+
stdin: "interactive"
128+
---
129+
130+
```py {monaco-run}
131+
name = input("請輸入姓名: ")
132+
print(f"你好 {name}！")
52133
```
53134
````
54135

55-
## Bundle `pyodide`
136+
## 進階設定
137+
138+
### 錯誤處理
139+
140+
該 addon 提供智慧錯誤處理：
141+
142+
- **套件未找到**：自動提示如何安裝 PyPI 套件
143+
- **輸入錯誤**：當程式碼需要 stdin 輸入時，提供詳細的設定說明
144+
- **語法錯誤**：顯示清晰的錯誤訊息和行號
145+
146+
### 支援的語言識別碼
147+
148+
您可以使用以下任一語言識別碼：
149+
150+
````md
151+
```python {monaco-run}
152+
print("Hello World")
153+
```
154+
155+
```py {monaco-run}
156+
print("Hello World")
157+
```
158+
````
159+
160+
### Pyodide 打包選項
161+
162+
預設情況下，當建置投影片時（即 `slidev build`），`pyodide` 套件會被替換為 CDN 版本。這是因為 https://github.com/pyodide/pyodide/issues/1949 的問題，使用打包版本時會導致已匯入的 Python 套件遺失。
163+
164+
若要打包本地版本的 `pyodide`，請將 `PYODIDE_BUNDLE` 環境變數設為 `true`：
165+
166+
```bash
167+
PYODIDE_BUNDLE=true slidev build
168+
```
169+
170+
⚠️ **注意**：使用本地打包版本時，無法在靜態建置中匯入 Python 套件。
171+
172+
## 開發
173+
174+
本專案使用 TypeScript 開發，主要檔案結構：
175+
176+
- `setup/code-runners.ts` - 主要的 Python 執行器實作
177+
- `vite.config.ts` - Vite 設定，處理 Pyodide 的打包邏輯
178+
- `package.json` - 專案設定和相依性
179+
180+
### 本地開發
181+
182+
```bash
183+
# 安裝相依性
184+
pnpm install
185+
186+
# 啟動開發伺服器
187+
pnpm dev
188+
189+
# 建置
190+
pnpm build
191+
```
192+
193+
## 致謝
194+
195+
本專案基於 [_Kerman](https://github.com/KermanX) 的原始開發工作。
196+
197+
**原開發者：**
198+
- _Kerman ([@KermanX](https://github.com/KermanX))
199+
200+
**此 Repo 維護者：**
201+
- CXPhoenix ([@CXPhoenix](https://github.com/CXPhoenix))
56202

57-
By default, when building slides (i.e. `slidev build`), the `pyodide` package will be replaced with the CDN version. This is because of https://github.com/pyodide/pyodide/issues/1949, which causes the imported python packages to be lost when using the bundled version.
203+
## 授權
58204

59-
To bundle the local version of `pyodide`, set the `PYODIDE_BUNDLE` environment variable to `true`. Note that in this way you can't import python packages in the static build.
205+
MIT License

‎package.json‎

Lines changed: 19 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "slidev-addon-python-runner",
3-
"version": "0.1.3",
3+
"version": "0.2.0",
44
"type": "module",
55
"scripts": {
66
"build": "slidev build",
@@ -19,27 +19,36 @@
1919
"url": "https://github.com/KermanX/slidev-addon-python-runner.git"
2020
},
2121
"author": {
22-
"name": "_Kerman",
23-
"email": "kermanx@qq.com",
24-
"url": "https://github.com/KermanX"
22+
"name": "CXPhoenix",
23+
"email": "cxph03n1x@gmail.com",
24+
"url": "https://github.com/CXPhoenix"
2525
},
26+
"contributors": [
27+
{
28+
"name": "_Kerman",
29+
"email": "kermanx@qq.com",
30+
"url": "https://github.com/KermanX"
31+
}
32+
],
2633
"files": [
2734
"setup",
2835
"README.md",
2936
"LICENSE",
3037
"vite.config.ts"
3138
],
3239
"devDependencies": {
33-
"@slidev/cli": "latest",
34-
"@slidev/client": "latest",
40+
"@slidev/cli": "^52.1.0",
41+
"@slidev/client": "^52.1.0",
3542
"@slidev/theme-default": "latest",
36-
"@slidev/types": "latest",
43+
"@slidev/types": "^52.1.0",
3744
"@types/node": "latest",
38-
"vite": "5",
45+
"vite": "latest",
3946
"vue": "latest"
4047
},
4148
"packageManager": "pnpm@9.14.3",
4249
"dependencies": {
43-
"pyodide": "^0.26.4"
50+
"@xterm/xterm": "^5.5.0",
51+
"playwright-chromium": "^1.55.0",
52+
"pyodide": "0.28.2"
4453
}
45-
}
54+
}

0 commit comments

Comments
 (0)