可以運(yùn)行代碼的網(wǎng)頁(yè)/文檔

我們?cè)谛聦W(xué)習(xí)一個(gè)項(xiàng)目時(shí)，會(huì)讀項(xiàng)目的文檔。有些項(xiàng)目的網(wǎng)頁(yè)/文檔里會(huì)嵌入代碼，點(diǎn)擊運(yùn)行就能看到效果，學(xué)習(xí)體驗(yàn)非常好。
如何把自己的項(xiàng)目文檔做成這種效果呢？本文介紹下相關(guān)技術(shù)。

0. 前端教程

很多前端項(xiàng)目的教程都是這種效果，原理很簡(jiǎn)單，讓用戶寫(xiě)的 html,css,js 在瀏覽器中直接執(zhí)行，不需要后端服務(wù)器。
例如 vue tutorials:
https://vuejs.org/tutorial/#step-1
但是支持的語(yǔ)言有限，只適合前端。

1. 在瀏覽器中“運(yùn)行” 腳本 + 后端執(zhí)行

對(duì)于其他語(yǔ)言，需要自己搭建后端服務(wù)器

需要自己搭建后端服務(wù)器，用戶在瀏覽器里操作、運(yùn)行 js/ipython，但實(shí)際上代碼是在后端 kernel 里執(zhí)行的。
所以本質(zhì)上是webshell (web IDE 原理也是這樣）


image.png

一些介紹文章:
http://wwj718.github.io/post/%E6%9E%B6%E6%9E%84/jupyter-notebook-architecture/
https://zhuanlan.zhihu.com/p/33105153
https://www.bilibili.com/video/BV1Q4411H7fJ?p=2&spm_id_from=pageDriver

簡(jiǎn)而言之，Jupyter Notebook是以網(wǎng)頁(yè)的形式打開(kāi)，可以在網(wǎng)頁(yè)頁(yè)面中直接編寫(xiě)代碼和運(yùn)行代碼，代碼的運(yùn)行結(jié)果也會(huì)直接在代碼塊下顯示的程序。如在編程過(guò)程中需要編寫(xiě)說(shuō)明文檔，可在同一個(gè)頁(yè)面中直接編寫(xiě)，便于作及時(shí)的說(shuō)明和解釋。

一個(gè)有趣的擴(kuò)展案例是美團(tuán)拿來(lái)對(duì)接spark 等大數(shù)據(jù)平臺(tái)：
https://www.infoq.cn/article/f32x6fc88r5rext8ulqz

有一些Jupyter的云托管服務(wù)，比如 google colab
https://www.ikkaro.com/zh-TW/%E8%B0%B7%E6%AD%8C%E5%90%88%E4%BD%9C%E5%AF%A6%E9%A9%97%E5%AE%A4%E6%88%96%E8%B0%B7%E6%AD%8C%E5%90%88%E4%BD%9C%E5%AF%A6%E9%A9%97%E5%AE%A4/

2. 瀏覽器瀏覽文檔/教程+ 云端托管服務(wù)執(zhí)行

給用戶一個(gè)在瀏覽器里操作的虛擬機(jī) + 教程文檔，文檔里的腳本點(diǎn)一下就能在虛擬機(jī)里執(zhí)行。

2.1. 國(guó)內(nèi)

shiyanlou

收費(fèi)

2.2. 國(guó)外

Katacoda

https://developer.aliyun.com/article/752183
相比于 shiyanlou 更open 些，能自己寫(xiě)教程
但是，已停運(yùn)：
https://mp.weixin.qq.com/s/oT9qch7OUjH6oYjLsxxcIQ

Killercoda

https://killercoda.com/
示例: https://killercoda.com/mosn-tutorial/course/layotto/layotto-with-istio

It's possible to run commands or scripts once a user opens a scenario. This allows to setup whatever is needed before the user starts problem solving or learning.

When using foreground scripts, all commands will be shown to the user in the terminal. When using background scripts, the user won't see the executed commands.

CloudYuga

https://cloudyuga.guru/
課程比 killercoda 多；但沒(méi)找到從 katacoda的遷移教程

Google colab

colab全稱為Colaboratory,是免費(fèi)的Jupyter運(yùn)行環(huán)境,并且完全在云端運(yùn)行。最重要的是免費(fèi)，而且不需要你自己去裝深度學(xué)習(xí)的環(huán)境

支持GPU，而且是免費(fèi)使用

2.3. 缺點(diǎn)

國(guó)內(nèi)的收費(fèi)，國(guó)外的要魔法上網(wǎng)，敲命令延遲高。
白嫖體驗(yàn)不好，本質(zhì)上是因?yàn)橐姆?wù)器資源，服務(wù)器要花錢。

3. 在瀏覽器中通過(guò) wasm 運(yùn)行 server 端

在瀏覽器中通過(guò) wasm 運(yùn)行 server 端的好處是：不用再消耗服務(wù)器資源

瀏覽器中運(yùn)行 tidb

體驗(yàn)地址： TiDB Playground (pingcap.com)

https://pingcap.com/zh/blog/tidb-in-the-browser-running-a-golang-database-on-wasm

https://en.pingcap.com/blog/tidb-in-the-browser-running-a-golang-database-on-webassembly/

瀏覽器中運(yùn)行 Postgresql

Postgresql playground:
https://www.bilibili.com/video/BV1bg411r7Fg/?spm_id_from=333.788&vd_source=0771a43f57c2ba3078c77e780c9c5e2f

https://www.crunchydata.com/blog/learn-postgres-at-the-playground

后來(lái)開(kāi)源了 postgresql wasm，見(jiàn) https://supabase.com/blog/postgres-wasm

瀏覽器中運(yùn)行 SQLite

SQLite can be compiled with emscripten without any modifications, and the sql.js library is a thin JS wrapper around the wasm code.

數(shù)據(jù)量太大，瀏覽器放不下怎么辦?

有了上述技術(shù)，我們自然會(huì)想到一個(gè)idea：如果只做靜態(tài)網(wǎng)站，可以不花錢租服務(wù)器、只用 github pages 等免費(fèi)托管服務(wù)做部署!
技術(shù)上，可以把 SQLite 編譯成 wasm 運(yùn)行在瀏覽器里，每次前端查詢db、畫(huà)圖時(shí)，其實(shí)是在調(diào)內(nèi)存里的 SQLite。這種方案在小數(shù)據(jù)量的情況下還好，但如果數(shù)據(jù)庫(kù)里數(shù)據(jù)量太大，每次打開(kāi)頁(yè)面要下載全量數(shù)據(jù)，太慢了。怎么辦？
有人做了個(gè)虛擬文件系統(tǒng)，對(duì) SQLite 提供 page 的抽象，當(dāng) SQLite 訪問(wèn)某個(gè) page 時(shí)，虛擬文件系統(tǒng)會(huì)通過(guò) HTTP Range 請(qǐng)求訪問(wèn)遠(yuǎn)端的靜態(tài)文件, 做到按需取數(shù)據(jù)，減少下載量。作者甚至做了"預(yù)取"等利用"局部性原理"的優(yōu)化。
打開(kāi)鏈接即可體驗(yàn)
https://phiresky.github.io/blog/2021/hosting-sqlite-databases-on-github-pages/

https://github.com/phiresky/sql.js-httpvfs

JupyterLite

體驗(yàn)地址(有bug的話可以掛梯子）:
https://jupyterlite.readthedocs.io/en/latest/_static/lab/

介紹:
https://blog.jupyter.org/jupyterlite-jupyter-%EF%B8%8F-webassembly-%EF%B8%8F-python-f6e2e41ab3fa
https://github.com/jupyterlite/demo

原理是把jupyter后端的python服務(wù)器跑在wasm里。支持很多解釋型語(yǔ)言：


image.png

瀏覽器中運(yùn)行 Streamlit

https://www.bilibili.com/video/BV14G4y1H7VM/?spm_id_from=333.1007.tianma.2-2-4.click&vd_source=0771a43f57c2ba3078c77e780c9c5e2f&t=74.8

https://edit.share.stlite.net/

4. 運(yùn)行markdown中的腳本

很多技術(shù)文檔是 markdown 文件，如果能直接運(yùn)行 md 文件中的腳本，會(huì)讓閱讀體驗(yàn)好很多。

4.1. 在網(wǎng)頁(yè)里渲染 markdown、運(yùn)行其中的 js

https://www.cnblogs.com/guoxiaoming/p/9550075.html
https://guoxiaoming.com/react-code-view/

只適合前端

4.2. IDE/編輯器 里執(zhí)行

IDE裝插件即可
https://hxyxyz.top/index.php/%E6%8A%80%E6%9C%AF/335.html
https://marketplace.visualstudio.com/items?itemName=Sycl.markdown-command-runner

或者用 Rmarkdown
https://sspai.com/post/42841

4.3. 在jupyter中運(yùn)行markdown格式腳本

https://zhuanlan.zhihu.com/p/39481175

5. 不只是教程: 你的下一個(gè)測(cè)試用例，何必是代碼？

想解決的問(wèn)題:
https://mosn.io/layotto/#/zh/development/test-quickstart
Quickstart 是項(xiàng)目的門面，如果新用戶進(jìn)入倉(cāng)庫(kù)后，發(fā)現(xiàn) Quickstart 文檔跑不起來(lái)，可能會(huì)失望的走掉。
所以我們要經(jīng)常性的測(cè)試 Quickstart, 保證能正常運(yùn)行。
但是…… 定期手動(dòng)測(cè)試 Quickstart、修復(fù)文檔中的異常，這個(gè)過(guò)程實(shí)在太花時(shí)間了：

image.png

5.1. 在命令行中運(yùn)行 markdown 中的 shell

希望能斷言返回狀態(tài)是不是異常

  • mdx
    自己寫(xiě)的
    https://github.com/seeflood/mdx
    todo:
    掃描指定目錄所有md文件，按順序執(zhí)行其中的腳本，支持寫(xiě)斷言塊

基于 mdsh 這個(gè)項(xiàng)目
https://seeflood.github.io/layotto/#/zh/development/test-quickstart
https://github.com/bashup/mdsh
https://gist.github.com/pjeby/c137ace4d91e61e8f1f80e92d84e8b70

  • Rmarkdown有命令行工具么?
    沒(méi)找到

5.2. 自動(dòng)測(cè)試你的文檔

https://mosn.io/layotto/#/zh/start/

5.3. 用文檔測(cè)試你的項(xiàng)目. Doc as tests

https://github.com/mosn/layotto/pull/669#issuecomment-1175729841
chore: use start --config parameters in some demos by seeflood · Pull Request #698 · mosn/layotto (github.com)

https://github.com/mosn/layotto/pull/669#issuecomment-1177224860
chore: layotto start without -c or --config by seeflood · Pull Request #3 · MichaelDeSteven/layotto (github.com)

6. Future work

記錄一些idea:

  • 文檔組件化

  • 文檔模板引擎

  • 文檔中引用代碼片段、代碼注釋

  • Online lab using wasm
    可以側(cè)邊欄打開(kāi)一個(gè) terminal, wasm運(yùn)行一個(gè) os，可以預(yù)先安裝一些軟件，例如docker.
    點(diǎn)擊命令，右邊terminal會(huì)自動(dòng)執(zhí)行

  • online lab using docker desktop
    同上，但是點(diǎn)擊后通過(guò)本地docker desktop執(zhí)行

  • mdx 和 https://github.com/charmbracelet/vhs 集成
    generate gif automatically · Issue #3 · seeflood/mdx (github.com)

最后編輯于 ：
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請(qǐng)聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時(shí)請(qǐng)結(jié)合常識(shí)與多方信息審慎甄別。
平臺(tái)聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點(diǎn)，簡(jiǎn)書(shū)系信息發(fā)布平臺(tái)，僅提供信息存儲(chǔ)服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

友情鏈接更多精彩內(nèi)容