Julia 文档编写指南如何编写与维护jldoctest代码块【免费下载链接】juliaThe Julia Programming Language项目地址: https://gitcode.com/gh_mirrors/ju/juliajldoctest是 Julia 文档体系中文档即测试机制的核心载体文档中写在jldoctest代码块里的示例会与真实的 Julia REPL 会话逐字比对既能向读者演示 API 用法又能在每次构建文档时自动回归验证。本指南以 doc/src/devdocs/contributing/jldoctests.md 为骨架结合 doc/make.jl、doc/src/devdocs/contributing/documentation.md 以及仓库中大量真实用例如 doc/src/base/reflection.md、doc/src/devdocs/cartesian.md、doc/src/manual/arrays.md系统讲解过滤器、setup/teardown 代码、跨代码块状态共享与语法版本控制帮助你在编写和评审 Julia 文档时写出可靠、易读、可维护的 doctest。从 docstring 到 jldoctest文档即测试什么是 doctestJulia 的文档构建基于 Documenter.jl。凡是写在 docstring 中的示例只要把代码块标注为jldoctest就会被当作测试用例执行。对此doc/src/devdocs/contributing/documentation.md 给出了最直接的说明Examples written within docstrings can be used as testcases known as doctests by annotating code blocks withjldoctest.一个最基本的 doctest 块长这样jldoctest julia uppercase(Docstring test) DOCSTRING TEST 这里有两个硬性要求必须模拟交互式 REPL 会话每一行输入都要以julia提示符开头多行输入续行使用空格缩进后面的输出必须与真实 Julia 在该输入下的输出逐字符一致建议在 doctest 上方加上# Examples标题这是 Julia 文档约定俗成的排版规范便于读者快速定位示例区。doctest 在文档构建中的执行方式doctest 的校验是在文档构建阶段完成的。doc/make.jl 中的makedocs调用接收命令行参数控制 doctest 行为doctest (doctestfix in ARGS) ? (:fix) : (doctestonly in ARGS) ? (:only) : (doctesttrue in ARGS) ? true : false,也就是说构建文档时可以通过三种开关控制 doctest命令行参数含义doctesttrue构建时运行 doctest 校验不匹配则报错doctestonly只运行 doctest不生成 HTML/PDF 文档doctestfix自动修正 doctest 输出把实际输出写回源文件而 doc/src/devdocs/agents/skills/doctests/SKILL.md 则给出了贡献者实际运行 doctest 的标准命令# 使用仓库内构建的 Julia推荐 make -C doc doctesttrue revisetrue值得注意的细节doctest 可以借助revisetrue实时加载对base/、stdlib/、Compiler/源码的修改整套 doctest 运行时间可能长达15 分钟不要中途终止、也不要设置超时doc/make.jl 中meta Dict(:DocTestSyntax VERSION)会把当前 Julia 版本作为全局默认语法版本注入文档构建详见下文语法版本控制一节。过滤器Filters消除平台与运行差异doctest 要求输出逐字符匹配但有些输出的内容是跨运行、跨平台不稳定的。此时应使用filter 选项用正则表达式把变化的部分抹掉。何时必须使用过滤器按 doc/src/devdocs/contributing/jldoctests.md出现以下情况时输出内容可能随运行而变应当加过滤器输出包含未初始化内存的数组来自undef或similar的数组其垃圾值不确定输出包含随机数输出包含计时信息如time的结果输出包含文件系统路径。文档中反复出现的常用过滤器序列原文档列出并维护了一批通用过滤器它们是 Julia 文档中使用频率最高的正则过滤器作用rint.jl:\d去掉code_*、which等内省宏输出中的行号rStacktrace:(\n \[[0-9]\].*)*在演示错误时隐藏完整堆栈跟踪rClosest candidates.*\n .*跳过MethodError打印的方法候选建议r .*剥离methods或which输出中的文件位置信息r\world\(MyStruct, \d:\d\)过滤 world age 编号出现在world相关输出中rwith \d methods忽略重定义函数时的方法计数r[0-9\.] seconds \(.*?\)移除带内存信息的计时输出r[0-9\.] seconds移除简单的计时结果r[0-9\.]过滤匿名函数等名称中的数字r([A-B] [0-5])、r[A-B] [X-Z] [0-5]处理进程输出的非确定性例如并行打印时的随机输出r(world\nhello|hello\nworld)允许交错输出按任意顺序出现例如多任务并发打印如果这些都不匹配你的场景就为变化的那段文本定制一条正则。合理使用过滤器能让 doctest 在不同平台和不同 Julia 版本上保持稳定。仓库中的真实用例doc/src/devdocs/inference.md 在展示推断输出时使用filterrtuple.jl:\d去掉文件路径行号doc/src/manual/control-flow.md 在演示异常时使用filter rStacktrace:(\n \[[0-9]\].*)*隐藏堆栈doc/src/base/reflection.md 把 setup 与 filter 组合使用jldoctest; setup :(using InteractiveUtils), filter r\w\.jl:\d julia InteractiveUtils.code_typed debuginfo:source (1,1) CodeInfo( essentials.jl:1190 within 1 ─ %1 intrinsic Base.add_int(x, y)::Int64 └── return %1 ) Int64 这里filter r\w\.jl:\d抹掉了essentials.jl:1190这样的文件名行号让示例不依赖具体源码行。注意 docstring 中的双重转义!重要陷阱docstring 本身会先处理一层转义序列然后才创建正则表达式。因此写在 docstring 里的过滤器正则必须双重转义反斜杠# ✅ 正确docstring 中的写法 r[\\d\\.] # ❌ 错误会被 docstring 提前处理掉一层反斜杠 r[\d\.]Setup 与 Teardown 代码短 setup 代码setup 选项如果 doctest 块执行前需要少量准备工作例如导入一个模块可以直接写在代码块头部的setup 选项里用:(...)引用一个表达式jldoctest; setup :(using InteractiveUtils) ... 仓库中 doc/src/base/reflection.md 就是典型用法反射相关的示例几乎都以setup :(using InteractiveUtils)开头因为code_typed、which等宏来自InteractiveUtils。setup 还可以直接写表达式而非quote引用doc/src/base/reflection.md 展示了这种写法setup (using Base: , sin)。长 setup 代码DocTestSetup元块如果 setup 代码较长或多个 doctest 块需要共享同一环境应该使用DocTestSetup元块而不是在每个块里重复meta DocTestSetup :(import Random; Random.seed!(1234)) 用完以后要显式关闭避免污染后续所有 doctest 块meta DocTestSetup nothing 仓库中的实际例子见 doc/src/devdocs/cartesian.md先用DocTestSetup quote ... import Base.Cartesian: nref ... end导入宏紧接着在jldoctest块里演示macroexpand nref 2 A i最后用DocTestSetup nothing收尾确保nref的导入不会泄漏到文档其余部分。Teardown 代码teardown 选项如果 doctest 执行后需要清理现场例如删除创建的临时文件、恢复当前工作目录使用teardown 选项。原文档给出的组合示例非常经典jldoctest; setup :(oldpath pwd(); cd(mktempdir())), teardown :(cd(oldpath)) ... 这里 setup 记录进入临时目录前的路径并cd到临时目录teardown 再cd回去。setup 中定义的变量oldpath在同一个块的 teardown 中依然可见因此这是一个完整的进-出配对。在多个代码块之间维护状态label 机制同名 jldoctest 块顺序执行、共享状态有时一个概念需要分几个代码块演示且后面的块要用到前面块产生的变量典型场景是演示可变性。此时给这些块一个相同的 labeljldoctest关键字后的名字即可jldoctest mutation_vs_rebind julia a [1,2,3] ... 然后在文档稍后的位置jldoctest mutation_vs_rebind julia a[1] 42 ... 同名块在 doctest 运行时按顺序依次执行因此第一个块创建的a在第二个块中仍然可用。这带来两个直接收益避免重复 setup 代码——环境只需要初始化一次更贴近真实 REPL 会话——读者按文档顺序逐块运行体验与一次完整会话一致。仓库中的 label 使用实例doc/src/manual/arrays.md 起的多个代码块使用cartesianindex标签串联doc/src/manual/arrays.md 起使用linindexing标签在多个块之间持续使用同一个索引变量演示线性索引与笛卡尔索引的行为差异。这些都是同 label 共享状态的典型场景。使用建议当一个代码片段需要把计算结果留给后续示例时给它一个 label 并在后面复用label 命名要有语义如cartesianindex方便读者理解块的关联不要给无关的块乱用同一 label它们会被当作连续会话顺序执行状态会互相影响。语法版本控制Syntax versioning按块指定语法版本syntax 选项当文档要介绍使用新 Julia 语法的功能时可以通过syntax 选项指定该 doctest 块需要的 Julia 语法版本。即使当前构建文档用的 Julia 默认语法较旧该块也会按指定版本解析jldoctest; syntax v1.14 julia result label myblock begin for i in 1:10 i 5 break myblock i * 2 end 0 end 12 上面示例中label ... break myblock i * 2是 Julia 1.14 引入的带标签中断语法因此块头声明syntax v1.14。全局默认DocTestSyntax元块对于以新语法为主的模块可以在元块中设置全局默认语法版本meta DocTestSyntax v1.14 规则是块级syntax 设置优先于全局DocTestSyntax。反过来全局设置也可以被单个块覆盖。兼容性说明Julia 1.14doctest 的语法版本控制功能本身要求 Julia 1.14 或更高版本。在旧版本 Julia 上运行 doctest 时syntax v1.14或更高版本的块会被跳过并发出警告不会导致构建失败。仓库中的全局默认注入有趣的是doc/make.jl 已经通过meta Dict(:DocTestSyntax VERSION)把当前构建 Julia 的版本作为全局DocTestSyntax默认值注入。这意味着直接用仓库内 Julia 构建文档时doctest 默认使用当前版本语法当文档中用syntax 标注了高于当前版本的语法时该块会被推迟/跳过在旧版 Julia 上从而保证新语法示例不会拖垮旧版本上的文档构建。编写与维护 jldoctest 的最佳实践总结输出必须可复现凡是输出中可能随运行变化的内容未初始化内存、随机数、计时、路径、行号、world age、方法计数、并发打印顺序等一律用filter 配合正则抹掉并优先复用上文的通用过滤器序列注意双重转义docstring 内的正则要写r[\\d\\.]而非r[\d\.]setup 宁短勿长一两行的准备用setup :(...)较长或多块共享的环境用DocTestSetup元块并在结束后置nothing善用 teardown创建临时文件、切换目录的示例用teardown 恢复现场同名 label 串联会话需要共享变量的连续示例用相同 label 模拟 REPL 会话避免重复 setup新语法按版本标注涉及新语法的块用syntax vx.y声明模块级默认用DocTestSyntax元块设置提交前务必本地验证按 doc/src/devdocs/agents/skills/doctests/SKILL.md 的指引任何对jldoctest块的增改都要运行make -C doc doctesttrue revisetrue验证且该过程可能长达 15 分钟不要中途终止。遵循这些规范jldoctest 才能既充当面向读者的活文档又担当跨平台、跨版本稳定的回归测试。延伸阅读doc/src/devdocs/contributing/jldoctests.md — 本文的原始出处文档doc/src/devdocs/contributing/documentation.md — Julia 文档贡献流程总览其中 Doctests 一节介绍了 doctest 的最基本形式doc/make.jl — 文档构建入口含 doctest 三档开关true/only/fix与DocTestSyntax全局默认注入doc/src/devdocs/agents/skills/doctests/SKILL.md — 提交前运行 doctest 的标准命令与注意事项doc/src/base/reflection.md —setupfilter组合使用的真实范例doc/src/devdocs/cartesian.md —DocTestSetup元块导入-使用-关闭的完整范例doc/src/manual/arrays.md — 同 label 多块共享状态的实践范例。【免费下载链接】juliaThe Julia Programming Language项目地址: https://gitcode.com/gh_mirrors/ju/julia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考