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

我們在新學習一個項目時,會讀項目的文檔萨螺。有些項目的網(wǎng)頁/文檔里會嵌入代碼,點擊運行就能看到效果愧驱,學習體驗非常好慰技。
如何把自己的項目文檔做成這種效果呢?本文介紹下相關技術组砚。

0. 前端教程

很多前端項目的教程都是這種效果吻商,原理很簡單,讓用戶寫的 html,css,js 在瀏覽器中直接執(zhí)行糟红,不需要后端服務器艾帐。
例如 vue tutorials:
https://vuejs.org/tutorial/#step-1
但是支持的語言有限,只適合前端盆偿。

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

對于其他語言柒爸,需要自己搭建后端服務器

需要自己搭建后端服務器,用戶在瀏覽器里操作事扭、運行 js/ipython捎稚,但實際上代碼是在后端 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

簡而言之求橄,Jupyter Notebook是以網(wǎng)頁的形式打開今野,可以在網(wǎng)頁頁面中直接編寫代碼和運行代碼,代碼的運行結果也會直接在代碼塊下顯示的程序罐农。如在編程過程中需要編寫說明文檔条霜,可在同一個頁面中直接編寫,便于作及時的說明和解釋涵亏。

一個有趣的擴展案例是美團拿來對接spark 等大數(shù)據(jù)平臺:
https://www.infoq.cn/article/f32x6fc88r5rext8ulqz

有一些Jupyter的云托管服務宰睡,比如 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. 瀏覽器瀏覽文檔/教程+ 云端托管服務執(zhí)行

給用戶一個在瀏覽器里操作的虛擬機 + 教程文檔蒲凶,文檔里的腳本點一下就能在虛擬機里執(zhí)行。

2.1. 國內(nèi)

shiyanlou

收費

2.2. 國外

Katacoda

https://developer.aliyun.com/article/752183
相比于 shiyanlou 更open 些夹厌,能自己寫教程
但是豹爹,已停運:
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 多裆悄;但沒找到從 katacoda的遷移教程

Google colab

colab全稱為Colaboratory,是免費的Jupyter運行環(huán)境,并且完全在云端運行矛纹。最重要的是免費庞钢,而且不需要你自己去裝深度學習的環(huán)境

支持GPU螃诅,而且是免費使用

2.3. 缺點

國內(nèi)的收費艾君,國外的要魔法上網(wǎng)采够,敲命令延遲高。
白嫖體驗不好冰垄,本質(zhì)上是因為要消耗服務器資源蹬癌,服務器要花錢。

3. 在瀏覽器中通過 wasm 運行 server 端

在瀏覽器中通過 wasm 運行 server 端的好處是:不用再消耗服務器資源

瀏覽器中運行 tidb

體驗地址: 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/

瀏覽器中運行 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

后來開源了 postgresql wasm虹茶,見 https://supabase.com/blog/postgres-wasm

瀏覽器中運行 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ù)量太大逝薪,瀏覽器放不下怎么辦?

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

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

JupyterLite

體驗地址(有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服務器跑在wasm里受啥。支持很多解釋型語言:


image.png

瀏覽器中運行 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. 運行markdown中的腳本

很多技術文檔是 markdown 文件做个,如果能直接運行 md 文件中的腳本鸽心,會讓閱讀體驗好很多。

4.1. 在網(wǎng)頁里渲染 markdown居暖、運行其中的 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中運行markdown格式腳本

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

5. 不只是教程: 你的下一個測試用例顽频,何必是代碼?

想解決的問題:
https://mosn.io/layotto/#/zh/development/test-quickstart
Quickstart 是項目的門面太闺,如果新用戶進入倉庫后糯景,發(fā)現(xiàn) Quickstart 文檔跑不起來,可能會失望的走掉省骂。
所以我們要經(jīng)常性的測試 Quickstart, 保證能正常運行蟀淮。
但是…… 定期手動測試 Quickstart、修復文檔中的異常钞澳,這個過程實在太花時間了:

image.png

5.1. 在命令行中運行 markdown 中的 shell

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

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

基于 mdsh 這個項目
https://seeflood.github.io/layotto/#/zh/development/test-quickstart
https://github.com/bashup/mdsh
https://gist.github.com/pjeby/c137ace4d91e61e8f1f80e92d84e8b70

  • Rmarkdown有命令行工具么?
    沒找到

5.2. 自動測試你的文檔

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

5.3. 用文檔測試你的項目. 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
    可以側邊欄打開一個 terminal, wasm運行一個 os策治,可以預先安裝一些軟件,例如docker.
    點擊命令兰吟,右邊terminal會自動執(zhí)行

  • online lab using docker desktop
    同上通惫,但是點擊后通過本地docker desktop執(zhí)行

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

最后編輯于
?著作權歸作者所有,轉載或內(nèi)容合作請聯(lián)系作者
  • 序言:七十年代末,一起剝皮案震驚了整個濱河市揽祥,隨后出現(xiàn)的幾起案子讽膏,更是在濱河造成了極大的恐慌,老刑警劉巖拄丰,帶你破解...
    沈念sama閱讀 222,729評論 6 517
  • 序言:濱河連續(xù)發(fā)生了三起死亡事件府树,死亡現(xiàn)場離奇詭異,居然都是意外死亡料按,警方通過查閱死者的電腦和手機奄侠,發(fā)現(xiàn)死者居然都...
    沈念sama閱讀 95,226評論 3 399
  • 文/潘曉璐 我一進店門,熙熙樓的掌柜王于貴愁眉苦臉地迎上來载矿,“玉大人垄潮,你說我怎么就攤上這事∶瓶” “怎么了弯洗?”我有些...
    開封第一講書人閱讀 169,461評論 0 362
  • 文/不壞的土叔 我叫張陵,是天一觀的道長逢勾。 經(jīng)常有香客問我牡整,道長,這世上最難降的妖魔是什么溺拱? 我笑而不...
    開封第一講書人閱讀 60,135評論 1 300
  • 正文 為了忘掉前任逃贝,我火速辦了婚禮谣辞,結果婚禮上,老公的妹妹穿的比我還像新娘沐扳。我一直安慰自己泥从,他們只是感情好,可當我...
    茶點故事閱讀 69,130評論 6 398
  • 文/花漫 我一把揭開白布沪摄。 她就那樣靜靜地躺著躯嫉,像睡著了一般。 火紅的嫁衣襯著肌膚如雪卓起。 梳的紋絲不亂的頭發(fā)上和敬,一...
    開封第一講書人閱讀 52,736評論 1 312
  • 那天凹炸,我揣著相機與錄音戏阅,去河邊找鬼。 笑死啤它,一個胖子當著我的面吹牛奕筐,可吹牛的內(nèi)容都是我干的。 我是一名探鬼主播变骡,決...
    沈念sama閱讀 41,179評論 3 422
  • 文/蒼蘭香墨 我猛地睜開眼离赫,長吁一口氣:“原來是場噩夢啊……” “哼!你這毒婦竟也來了塌碌?” 一聲冷哼從身側響起渊胸,我...
    開封第一講書人閱讀 40,124評論 0 277
  • 序言:老撾萬榮一對情侶失蹤,失蹤者是張志新(化名)和其女友劉穎台妆,沒想到半個月后翎猛,有當?shù)厝嗽跇淞掷锇l(fā)現(xiàn)了一具尸體,經(jīng)...
    沈念sama閱讀 46,657評論 1 320
  • 正文 獨居荒郊野嶺守林人離奇死亡接剩,尸身上長有42處帶血的膿包…… 初始之章·張勛 以下內(nèi)容為張勛視角 年9月15日...
    茶點故事閱讀 38,723評論 3 342
  • 正文 我和宋清朗相戀三年切厘,在試婚紗的時候發(fā)現(xiàn)自己被綠了。 大學時的朋友給我發(fā)了我未婚夫和他白月光在一起吃飯的照片懊缺。...
    茶點故事閱讀 40,872評論 1 353
  • 序言:一個原本活蹦亂跳的男人離奇死亡疫稿,死狀恐怖,靈堂內(nèi)的尸體忽然破棺而出鹃两,到底是詐尸還是另有隱情遗座,我是刑警寧澤,帶...
    沈念sama閱讀 36,533評論 5 351
  • 正文 年R本政府宣布俊扳,位于F島的核電站途蒋,受9級特大地震影響,放射性物質(zhì)發(fā)生泄漏拣度。R本人自食惡果不足惜碎绎,卻給世界環(huán)境...
    茶點故事閱讀 42,213評論 3 336
  • 文/蒙蒙 一螃壤、第九天 我趴在偏房一處隱蔽的房頂上張望。 院中可真熱鬧筋帖,春花似錦奸晴、人聲如沸。這莊子的主人今日做“春日...
    開封第一講書人閱讀 32,700評論 0 25
  • 文/蒼蘭香墨 我抬頭看了看天上的太陽。三九已至代箭,卻和暖如春墩划,著一層夾襖步出監(jiān)牢的瞬間,已是汗流浹背嗡综。 一陣腳步聲響...
    開封第一講書人閱讀 33,819評論 1 274
  • 我被黑心中介騙來泰國打工乙帮, 沒想到剛下飛機就差點兒被人妖公主榨干…… 1. 我叫王不留,地道東北人极景。 一個月前我還...
    沈念sama閱讀 49,304評論 3 379
  • 正文 我出身青樓察净,卻偏偏與公主長得像,于是被迫代替她去往敵國和親盼樟。 傳聞我的和親對象是個殘疾皇子氢卡,可洞房花燭夜當晚...
    茶點故事閱讀 45,876評論 2 361

推薦閱讀更多精彩內(nèi)容