我們在新學習一個項目時，會讀項目的文檔萨螺。有些項目的網(wǎng)頁/文檔里會嵌入代碼，點擊運行就能看到效果愧驱，學習體驗非常好慰技。
如何把自己的項目文檔做成這種效果呢？本文介紹下相關技術组砚。
0. 前端教程
很多前端項目的教程都是這種效果吻商，原理很簡單，讓用戶寫的 html,css,js 在瀏覽器中直接執(zhí)行糟红，不需要后端服務器艾帐。
例如 vue tutorials:
https://vuejs.org/tutorial/#step-1
但是支持的語言有限，只適合前端盆偿。
1. 在瀏覽器中“運行” 腳本 + 后端執(zhí)行
對于其他語言柒爸，需要自己搭建后端服務器
- jupyter notebook
示例: https://jupyter.org/try-jupyter/retro/notebooks/?path=notebooks/Intro.ipynb
image.png
需要自己搭建后端服務器，用戶在瀏覽器里操作事扭、運行 js/ipython捎稚，但實際上代碼是在后端 kernel 里執(zhí)行的。
所以本質(zhì)上是webshell (web IDE 原理也是這樣）
一些介紹文章:
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
支持從 Katacoda 遷移
K8s 社區(qū)也遷移到了 Killercoda
Katacoda to Killercoda Migration GuideForeground Background Scripts
https://killercoda.com/examples/scenario/foreground-background-scripts
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.
- assets
把自己的東西掛載進文件系統(tǒng)里
https://killercoda.com/examples/scenario/upload-assets
https://github.com/killercoda/scenario-examples/tree/main/upload-assets
CloudYuga
https://cloudyuga.guru/
課程比 killercoda 多裆悄；但沒找到從 katacoda的遷移教程
Google colab
colab全稱為Colaboratory,是免費的Jupyter運行環(huán)境,并且完全在云端運行矛纹。最重要的是免費庞钢，而且不需要你自己去裝深度學習的環(huán)境
支持GPU螃诅，而且是免費使用
教程
https://zhuanlan.zhihu.com/p/54389036
https://zhuanlan.zhihu.com/p/367893594
http://www.reibang.com/p/a42d69568966案例
很多 AI 模型的 demo 會放到 colab，用戶打開 web 即可體驗模型肴敛。
例如 2d 圖片轉 3d 的demo
https://www.bilibili.com/video/BV11r4y1D7Wk/
https://colab.research.google.com/drive/1706ToQrkIZshRSJSHvZ1RuCiM__YX3Bz
例如啟動 Avatarify 服務器
https://colab.research.google.com/github/alievk/avatarify/blob/master/avatarify.ipynb
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里受啥。支持很多解釋型語言：
瀏覽器中運行 Streamlit
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、修復文檔中的異常钞澳，這個過程實在太花時間了：
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)
