ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

Jupytext Markdown 格式实战:将 Clojure/Clojupyter 笔记本转换为可读的 Markdown 文档

Jupytext Markdown 格式实战:将 Clojure/Clojupyter 笔记本转换为可读的 Markdown 文档 开发工具【免费下载链接】jupytextJupyter Notebooks as Markdown Documents, Julia, Python or R scripts项目地址https://gitcode.com/gh_mirrors/ju/jupytext点击查看免费下载本篇技术指南以 Jupytext 仓库中html-demo.ipynb一个 Clojupyter 演示笔记本转换而成的 Markdown 镜像文件tests/data/notebooks/outputs/ipynb_to_md/html-demo.md为完整样本系统讲解 Jupytext Markdown 格式的语法骨架、非 PythonClojure笔记本的转换结果以及底层镜像测试机制。读完本文你将掌握Jupytext Markdown 格式中 YAML 头、代码单元、Markdown 单元的表示规则如何把一个包含 HTML/SVG 渲染、外部依赖注入、前端图表库集成的 Clojure 笔记本完整无损地转换为可被 GitHub、VS Code 等渲染的 Markdown 文档并理解其往返round-trip保真由仓库测试如何保障。一、为什么用 Markdown 格式承载 NotebookJupytext 的核心能力是把 Jupyter Notebook.ipynb保存为纯文本格式其中 Markdown 是最适合文本多于代码场景的载体——教程、书籍、技术博客天然与之匹配。在官方格式文档website/src/content/docs/formats/markdown.md中明确说明以 Markdown 表示的笔记本能被大多数 Markdown 编辑器或渲染器包括 GitHub良好渲染非常适合内容型笔记本。与 Python 笔记本不同Clojure 笔记本在 Jupyter 生态中依赖 Clojupyter 内核。本文使用的示例正是一个完整的 Clojupyter 高级功能演示它在代码单元中通过display/hiccup-html输出 HTML 与 SVG通过clojupyter.misc.helper动态拉取外部 Clojure 依赖data.json与外部 JavaScript 库Highcharts并最终生成可交互的折线图。这样的笔记本如何被 Jupytext 表达为 Markdown正是本文要逐行剖析的内容。二、Jupytext Markdown 格式的骨架YAML 头任何 Jupytext 文本格式包括 Markdown都以一个可选的 YAML 头开头用来保存选定的笔记本元数据。html-demo.md的头部是最精简的形态仅记录内核信息--- jupyter: kernelspec: display_name: Clojure language: clojure name: clojure ---这段 YAML 与源文件 tests/data/notebooks/inputs/ipynb_clojure/html-demo.ipynb 的metadata.kernelspec完全一致display_name: Clojure、language: clojure、name: clojure说明转换把内核信息原样带入了文本文件。对照官方格式文档可知jupyter:一节可存放自定义笔记本元数据如author、title并与笔记本元数据保持同步需要导出更多元数据时可参考文档中metadata filtering相关章节若希望 Markdown 文档按 Markdown 标题切分单元可在jupytext一节加入split_at_heading: true或在jupytext.toml配置文件中全局开启split_at_heading true。从源码角度看该格式在 src/jupytext/formats.py 中注册为format_namemarkdown、extension.md并兼容.markdown扩展名是 Jupytext 的默认文本格式之一。转换时的实际调用链为jupytext主模块中notebook_to_md(self.filter_notebook(nb, metadata))见 src/jupytext/jupytext.py其中filter_notebook依据元数据过滤规则裁剪后才落盘。三、示例正文与转换结果逐段解读html-demo.md正文完整对应源笔记本的 9 个单元Markdown 单元逐字保留、以两个空行分隔代码单元用三重反引号包裹并显式标注语言clojure。下面按主题段完整复现并解读。3.1 标题与简介# Clojupyter Demo This example notebook is from the Clojupyter project. This notebook demonstrates some of the more advanced features of Clojupyter.转换规则印证在 Jupytext Markdown 格式中Markdown 单元是逐字插入的verbatim不做内容改写因此标题、链接、段落原样保留。这保证了你在 GitHub 或 VS Code 中看到的预览与笔记本内渲染一致。3.2 显示 HTMLdisplay/hiccup-html## Displaying HTML To display HTML, youll need to require a clojupyter helper function to change the cell output(require [clojupyter.misc.display :as display])(println should print some text) ;; displaying html (display/hiccup-html [:ul [:li a [:i emphatic] idea] [:li a [:b bold] idea] [:li an [:span {:style text-decoration: underline;} important] idea]])关键细节代码单元的语言标注clojure直接取自笔记本metadata.language_info.name源 ipynb 中为clojure版本1.8.0file_extension为.clj。display/hiccup-html接收 Hiccup 向量Clojure 风格的 HTML 描述在单元输出中生成ul列表。对照源 ipynb 的outputs该单元同时包含stdout流输出 should print some text与text/html的execute_result——Jupytext Markdown 格式不保存输出因此输出只存在于执行笔记本时文本文件中仅保留代码本体。这也是该格式适合版本控制与协作的原因输出不会造成 diff 噪声。3.3 用同一 API 渲染 SVGWe can also use this to render SVG:(display/hiccup-html [:svg {:height 100 :width 100 :xmlns http://www.w3.org/2000/svg} [:circle {:cx 50 :cy 40 :r 40 :fill red}]])由于hiccup-html输出的是任意text/htmlSVG 同样只是普通 HTML。源 ipynb 中该单元的输出为svg height100 width100 ...circle .../circle/svg转换后的 Markdown 不携带这段 HTML 输出仅保留生成它的 Hiccup 表达式。这说明 Markdown 格式的保真是源码级的单元边界、代码文本、Markdown 文本完整保留而执行产物被有意剔除。3.4 注入外部 Clojure 依赖## Adding External Clojure Dependencies You can fetch external Clojure dependencies using the clojupyter.misc.helper namespace.(require [clojupyter.misc.helper :as helper])(helper/add-dependencies [org.clojure/data.json 0.2.6]) (require [clojure.data.json :as json])(json/write-str {:a 1 :b [2, 3] :c c})这里演示了 Clojupyter 的动态依赖加载helper/add-dependencies以 Clojure 坐标group/artifact version拉取 Maven 依赖随后clojure.data.json即可用json/write-str把 Clojure 数据结构序列化为 JSON 字符串源 ipynb 输出为{\a\:1,\b\:[2,3],\c\:\c\}。这些单元在 Markdown 文件中按序排列与 ipynb 中execution_count递增的顺序一一对应。3.5 集成外部 JavaScript 库Highcharts 交互绘图## Adding External Javascript Dependency Since you can render arbitrary HTML using display/hiccup-html, its pretty easy to use external Javascript libraries to do things like generate charts. Heres an example using Highcharts.First, we use a cell to add javascript to the running notebook:(helper/add-javascript https://code.highcharts.com/highcharts.js)Now we define a function which takes Clojure data and returns hiccup HTML to display:(defn plot-highchart [highchart-json] (let [id (str (java.util.UUID/randomUUID)) code (format Highcharts.chart(%s, %s ); id, (json/write-str highchart-json))] (display/hiccup-html [:div [:div {:id id :style {:background-color red}}] [:script code]])))Now we can make generate interactive plots (try hovering over plot):(def raw-data (map #( (* 22 ( % (Math/random)) 78)) (range))) (def>def test_ipynb_to_md(ipynb_file, no_jupytext_version_number): assert_conversion_same_as_mirror(ipynb_file, md, ipynb_to_md)该测试遍历tests/data/notebooks/inputs下所有ipynb文件ipynb_file参数化以md格式做 ipynb → md → ipynb 的往返转换并断言结果与既有镜像文件outputs/ipynb_to_md/目录一致。html-demo.md正是这一机制的镜像输出之一因而它天然具备可回归验证的权威性只要仓库测试通过就说明该文档与源 ipynb 可双向无损还原。与之配套的还有md_to_ipynb方向的测试同一文件后半部分以及同一源笔记本的其他格式镜像tests/data/notebooks/outputs/ipynb_to_script/html-demo.clj——light 脚本格式代码单元直接按序排列Markdown 单元以;;注释行表达tests/data/notebooks/outputs/ipynb_to_percent/html-demo.clj——percent 格式以# %%标记分隔单元tests/data/notebooks/outputs/ipynb_to_hydrogen/html-demo.clj——hydrogen 格式VSCode 友好tests/data/notebooks/outputs/ipynb_to_Rmd/html-demo.Rmd——R Markdown 格式。同一份 Clojure 内容在多种文本格式间自由切换是 Jupytext 一份笔记本、多种文本表示设计的直接体现。另外在 tests/functional/round_trip/test_mirror.py 的test_ipynb_to_myst中html-demo与julia_functional_geometry、xcpp_by_quantstack一起被显式跳过pytest.skip()。从源码结构看这暗示该样本在 MyST 格式下存在已知的往返差异例如行内%s格式串、Hiccup 数据等内容的特殊处理因此不参与 MyST 镜像断言——这也提醒读者不同文本格式对同一笔记本的保真程度可能有细微差别选用格式时应以实际往返结果为准。五、如何在自己项目中复现与使用5.1 在 Jupyter 中打开 Markdown 笔记本把html-demo.md这类文件放入 Jupyter 目录后Jupytext 的内容管理器会把它识别为笔记本.md文件与.ipynb等价可打开、可运行。以文本形式编辑保存后重新在 Jupyter 中打开即可看到单元结构被完整还原。5.2 命令行转换安装 Jupytext 后可在终端执行 ipynb → md 转换jupytext --to md html-demo.ipynb反向转换jupytext --to ipynb html-demo.md--to md即映射到formats.py中注册的markdown格式.md。更精细的控制可通过--set-formats建立配对关系例如让每个.ipynb自动维护一个.md副本配合 Git 进行纯文本 diff。5.3 单元标记与元数据的进阶写法html-demo.md未用到单元元数据但官方格式文档website/src/content/docs/formats/markdown.md给出了 Markdown 格式下单元元数据的标准语法与本示例同属一套格式体系代码单元元数据语言标注后追加keyvalue值按 JSON 编码如python tags[parameters]Raw 单元用 HTML 注释包裹!-- #raw -- ... !-- #endraw --同样支持keyvalue元数据Markdown 单元显式标记!-- #md --、!-- #markdown --或 VS Code 可折叠的!-- #region --/!-- #endregion --不希望某段代码在 Jupyter 中被当作可执行代码单元时可去掉语言标注、改用~~~python围栏、加.noeval属性或activemd元数据。5.4 适用前提与限制示例面向 Clojure/Clojupyter 内核若要在本机运行需先安装 Clojupyter 内核仓库本身不提供内核仅做文本查看/版本管理则无需内核。Markdown 格式不保存单元输出与执行计数若要保留输出请使用.ipynb本体。同一仓库还提供md:mystMyST需 Python ≥ 3.6 与 myst 依赖、md:pandoc需 pandoc ≥ 2.7.2、qmdQuarto等衍生 Markdown 系格式各有不同保真特性如html-demo在 MyST 下不参与镜像断言。六、小结通过html-demo.md这一个完整样本本文覆盖了 Jupytext Markdown 格式的三层知识语法层YAML 头、围栏代码单元、逐字 Markdown 单元、单元元数据扩展语法、内容层HTML/SVG 渲染、动态依赖注入、前端图表集成的 Clojure 代码如何被无损表达、工程层镜像测试机制如何保证 ipynb 与 md 双向往返保真以及多格式镜像的并存关系。这份文件既是可运行的笔记本示例也是格式规范的活教材——这正是 Jupytext 用输出即样例的方式为开发者提供的可检索、可验证的文档形态。后续如需深入研究可继续阅读 tests/data/notebooks/outputs/ipynb_to_md/ 目录下其余镜像文件如ir_notebook.md、julia_benchmark_plotly_barchart.md等多语言样本以及 website/src/content/docs/formats/markdown.md 的完整格式说明。赞分享开发工具【免费下载链接】jupytextJupyter Notebooks as Markdown Documents, Julia, Python or R scripts项目地址https://gitcode.com/gh_mirrors/ju/jupytext点击查看免费下载相关推荐Jupytext 实战将 Octave 笔记本转换为 MyST Markdown 文档Jupytext 实战将 Octave 笔记本转换为 MyST Markdown 文档 导读本文以 Jupytext 仓库中的真实转换产物 tests/da开发工具Jupytext 实战将 .NET C 交互式笔记本转换为 MyST Markdown 文本格式Jupytext 实战将 .NET C 交互式笔记本转换为 MyST Markdown 文本格式 Jupytext 的核心能力是让 Jupyter 笔记本以可开发工具30分钟做出游戏粒子特效Cocos引擎ParticleSystem实战笔记30分钟做出游戏粒子特效Cocos引擎ParticleSystem实战笔记 雨幕压城、火星四溅——你见过的那些电影感画面本质都是成千上万个微小粒子在被程序精开发工具上一篇Anime.js 动画引擎完整使用指南10个快速上手的终极技巧下一篇Self-driving-car道路定义与交通模拟构建真实驾驶环境的5个技巧创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表