Julia 仓库 jldoctest 编写与验证实战指南基于 Agent SkillSKILL.md的完整工作流【免费下载链接】juliaThe Julia Programming Language项目地址: https://gitcode.com/gh_mirrors/ju/juliajldoctest是 Julia 文档系统中将 docstring 内代码示例变成可自动测试用例的机制也是 Julia 主仓库base/、stdlib/、Compiler/ 与 doc/ 目录维护代码示例正确性的核心工具。本文以仓库内置的 Agent Skill 文档 doctests/SKILL.md 为主体结合 jldoctests.md 最佳实践与 doc/make.jl 的构建实现系统讲解jldoctest的编写要点、常见过滤器、setup/teardown 机制以及本地验证的完整命令流程。读完本文你将能够在 Julia 仓库中安全地新增或修改jldoctest代码块并在提交 PR 前独立完成本地验证。一、背景Agent Skill 与 doctests 技能Julia 仓库将面向 AI Agent 的项目级技能集中存放于doc/src/devdocs/agents/skills/目录每个技能遵循 Agent Skills。其中doctests技能的元信息如下name: doctests description: Write and verify Julia jldoctest code blocks. Use whenever adding or changing a jldoctest block in a docstring (base/, stdlib/, Compiler/) or under doc/, and before opening a PR that touches doctests.这段描述界定了技能的适用范围只要在 docstringbase/、stdlib/、Compiler/ 下的源码注释或 doc/ 下的文档中新增、修改了任何jldoctest代码块并且在打开涉及 doctest 的 PR 之前都应启用该技能。仓库的文档构建系统doc/make.jl 中的generate_agent_skill_docs()会读取每个技能的SKILL.md将其渲染进 Agentic Devdocs 章节因此这份技能文档本身就是 Julia 文档站点的一部分。该技能的核心工作流分两步先复习编写规范再执行验证。二、编写 jldoctest先复习最佳实践在动手写新的 doctest 之前技能明确要求先通读 doc/src/devdocs/contributing/jldoctests.md重点确认三件事filters过滤器、labels标签与 setup code前置代码。这份指南的要点如下。2.1 过滤器filter应对非确定性输出只要输出内容在不同运行环境下可能变化就必须使用filter 选项。常见场景包括包含未初始化内存的数组来自undef或similar包含随机数包含计时信息包含文件系统路径。仓库文档沉淀了一批反复使用的过滤正则可直接套用过滤正则用途rint.jl:\\d去掉内省宏输出中的行号rStacktrace:(\\n \\[0-9\\].*)*演示错误时隐藏堆栈回溯rClosest candidates.*\\n .*跳过MethodError打印的方法建议r .*去掉methods或which输出中的文件位置r\\world\\(MyStruct, \\d:\\d\\)过滤 world age 编号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)允许交错输出world/hello的任意顺序如果上述都不匹配就需要自行编写一个能剔除易变文本的正则表达式。合理使用过滤器能保证 doctest 跨平台、跨 Julia 版本保持稳定。⚠️ docstring 中的双重转义在 docstring 内编写正则过滤器时反斜杠必须双重转义。例如应写r[\\d\\.]而不是r[\d\.]因为 docstring 自身会先处理一次转义序列之后正则才会被创建。仓库源码中有大量实践样例例如 base/abstractarray.jl 的jldoctest; filter r[01]以及 base/abstractdict.jl 中对表格输出使用filter r^\\s\\S.*\$m等多行正则过滤的写法。2.2 Setup 与 teardown前置与清理代码简短的前置表达式可用内联的setup 选项jldoctest; setup :(using InteractiveUtils) ... 如果 setup 代码较长或多个代码块需要相同环境应使用DocTestSetup元块meta blockmeta DocTestSetup :(import Random; Random.seed!(1234)) 并在使用完毕后通过DocTestSetup nothing关闭meta DocTestSetup nothing 需要清理代码时例如删除临时文件、恢复当前目录可使用teardown 选项jldoctest; setup :(oldpath pwd(); cd(mktempdir())), teardown :(cd(oldpath)) ... 2.3 标签label在代码块之间维持状态相关的 doctest 块可以通过jldoctest关键字后的同名标签共享状态。Julia 手册就用这种模式演示可变mutation与重绑定rebinding的区别jldoctest mutation_vs_rebind julia a [1,2,3] ... jldoctest mutation_vs_rebind julia a[1] 42 ... 同名代码块在 doctest 运行时按顺序执行第一个块中创建的变量在后续块中仍然可用。当某个片段的计算结果需要在后续示例中继续使用时给它们加上相同标签即可这样既避免重复 setup 代码也更贴近真实 REPL 会话的行为。2.4 语法版本化syntax 当文档涉及新 Julia 语法时可用syntax 选项为 doctest 指定所需语法版本jldoctest; syntax v1.14 julia result label myblock begin for i in 1:10 i 5 break myblock i * 2 end 0 end 12 这保证代码块按指定语法版本解析即使文档是用更老的默认语法构建的新语法特性的 doctest 也能通过。对于以新语法为主的模块可在元块中设置全局默认值meta DocTestSyntax v1.14 单块的syntax 设置会覆盖全局DocTestSyntax。注意doctest 的语法版本化需要 Julia 1.14 及以上在更老的 Julia 上运行时syntax v1.14及以上的代码块会被跳过并给出警告。仓库的构建脚本正是通过meta Dict(:DocTestSyntax VERSION)将当前版本注入文档构建的见 doc/make.jl。三、验证流程每次 doctest 改动必须执行技能文档强调只要修改了任何jldoctest块就必须验证。验证步骤如下。第 1 步回顾最佳实践再次阅读 doc/src/devdocs/contributing/jldoctests.md特别确认改动的 doctest 是否需要 filters、labels 或 setup code。第 2 步运行 doctest提供两种运行方式按偏好选择使用预构建的 juliaup 版本运行make -C doc doctesttrue revisetrue JULIA_EXECUTABLE$HOME/.juliaup/bin/julia使用仓库内构建的 Julia 运行推荐make -C doc doctesttrue revisetrue这是首选方式且不要传递其他任何选项。⏱️ 重要提醒doctest 运行可能需要长达15 分钟。在完成之前不要终止doctest也不要为其设置超时例如在使用 ChatGPT 这类工具时可能需要调大yield_timeout_ms。3.1 命令背后的构建机制上述命令的含义可以从 doc/Makefile 中得到印证echo To run doctests, use make target doctesttrue echo To fix outdated doctests, use make target doctestfix echo To run doctests using Revise (to test changes without rebuilding the sysimage), use make target doctesttrue revisetruedoctesttrue开启 doctest 检查模式doctestfix自动修复过期的 doctest 输出直接改写文档中与运行结果不符的代码块输出需人工确认改动是否符合预期revisetrue借助 Revise 机制在不重新构建 sysimage 的情况下测试对源码的修改显著缩短迭代周期JULIA_EXECUTABLE...指定实际执行 doctest 的 Julia 可执行文件便于使用系统安装的 juliaup 版本。这些开关在 doc/make.jl 中被转换为 Documenter.jl 的doctest参数命令行含doctestfix时为:fix含doctestonly时为:only含doctesttrue时为true否则为false。其中doctestonly模式仅运行 doctest 而不构建完整文档适合快速回归。四、仓库中的真实案例佐证jldoctest并非孤立机制而是深度嵌入 Julia 主仓库的文档体系base/ 源码几乎所有 docstring 都包含 doctest例如 base/abstractarray.jl47 处、base/abstractdict.jl12 处等覆盖了过滤器、标签、多行正则等各类写法是学习jldoctest语法的最佳活教材。文档章节完整规范收录在 doc/src/devdocs/contributing/jldoctests.md并作为 Contributors Guide 的一部分被 doc/make.jl 注册到文档导航中。Agent 技能体系doctests 技能与 test-changes、c-static-analysis、external-deps 等技能共同构成 Julia 的 Agentic Devdocs 体系见 doc/src/devdocs/agents/README.md 与 doc/src/devdocs/agents/skills/doctests/SKILL.md。五、实操清单在提交任何涉及 doctest 的改动前对照以下清单自查编写阶段新写或修改jldoctest前复习 jldoctests.md判断需求输出是否可能变化内存未初始化、随机数、计时、路径是否需要filter docstring 内的正则是否已双重转义组织代码是否需要setup /DocTestSetup/teardown 多个块需要共享状态时是否已使用相同标签是否涉及新语法syntax 执行验证使用推荐命令make -C doc doctesttrue revisetrue仓库内 Julia运行 doctest耐心等待最多等待 15 分钟期间不终止、不设超时若输出过期可改用doctestfix自动修复后人工核对。遵循这套流程既能保证文档示例长期可运行也能让 doctest 成为 Julia 仓库中值得信赖的“活文档”。【免费下载链接】juliaThe Julia Programming Language项目地址: https://gitcode.com/gh_mirrors/ju/julia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Julia 仓库 jldoctest 编写与验证实战指南：基于 Agent Skill（SKILL.md）的完整工作流
Julia 仓库 jldoctest 编写与验证实战指南基于 Agent SkillSKILL.md的完整工作流【免费下载链接】juliaThe Julia Programming Language项目地址: https://gitcode.com/gh_mirrors/ju/juliajldoctest是 Julia 文档系统中将 docstring 内代码示例变成可自动测试用例的机制也是 Julia 主仓库base/、stdlib/、Compiler/ 与 doc/ 目录维护代码示例正确性的核心工具。本文以仓库内置的 Agent Skill 文档 doctests/SKILL.md 为主体结合 jldoctests.md 最佳实践与 doc/make.jl 的构建实现系统讲解jldoctest的编写要点、常见过滤器、setup/teardown 机制以及本地验证的完整命令流程。读完本文你将能够在 Julia 仓库中安全地新增或修改jldoctest代码块并在提交 PR 前独立完成本地验证。一、背景Agent Skill 与 doctests 技能Julia 仓库将面向 AI Agent 的项目级技能集中存放于doc/src/devdocs/agents/skills/目录每个技能遵循 Agent Skills。其中doctests技能的元信息如下name: doctests description: Write and verify Julia jldoctest code blocks. Use whenever adding or changing a jldoctest block in a docstring (base/, stdlib/, Compiler/) or under doc/, and before opening a PR that touches doctests.这段描述界定了技能的适用范围只要在 docstringbase/、stdlib/、Compiler/ 下的源码注释或 doc/ 下的文档中新增、修改了任何jldoctest代码块并且在打开涉及 doctest 的 PR 之前都应启用该技能。仓库的文档构建系统doc/make.jl 中的generate_agent_skill_docs()会读取每个技能的SKILL.md将其渲染进 Agentic Devdocs 章节因此这份技能文档本身就是 Julia 文档站点的一部分。该技能的核心工作流分两步先复习编写规范再执行验证。二、编写 jldoctest先复习最佳实践在动手写新的 doctest 之前技能明确要求先通读 doc/src/devdocs/contributing/jldoctests.md重点确认三件事filters过滤器、labels标签与 setup code前置代码。这份指南的要点如下。2.1 过滤器filter应对非确定性输出只要输出内容在不同运行环境下可能变化就必须使用filter 选项。常见场景包括包含未初始化内存的数组来自undef或similar包含随机数包含计时信息包含文件系统路径。仓库文档沉淀了一批反复使用的过滤正则可直接套用过滤正则用途rint.jl:\\d去掉内省宏输出中的行号rStacktrace:(\\n \\[0-9\\].*)*演示错误时隐藏堆栈回溯rClosest candidates.*\\n .*跳过MethodError打印的方法建议r .*去掉methods或which输出中的文件位置r\\world\\(MyStruct, \\d:\\d\\)过滤 world age 编号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)允许交错输出world/hello的任意顺序如果上述都不匹配就需要自行编写一个能剔除易变文本的正则表达式。合理使用过滤器能保证 doctest 跨平台、跨 Julia 版本保持稳定。⚠️ docstring 中的双重转义在 docstring 内编写正则过滤器时反斜杠必须双重转义。例如应写r[\\d\\.]而不是r[\d\.]因为 docstring 自身会先处理一次转义序列之后正则才会被创建。仓库源码中有大量实践样例例如 base/abstractarray.jl 的jldoctest; filter r[01]以及 base/abstractdict.jl 中对表格输出使用filter r^\\s\\S.*\$m等多行正则过滤的写法。2.2 Setup 与 teardown前置与清理代码简短的前置表达式可用内联的setup 选项jldoctest; setup :(using InteractiveUtils) ... 如果 setup 代码较长或多个代码块需要相同环境应使用DocTestSetup元块meta blockmeta DocTestSetup :(import Random; Random.seed!(1234)) 并在使用完毕后通过DocTestSetup nothing关闭meta DocTestSetup nothing 需要清理代码时例如删除临时文件、恢复当前目录可使用teardown 选项jldoctest; setup :(oldpath pwd(); cd(mktempdir())), teardown :(cd(oldpath)) ... 2.3 标签label在代码块之间维持状态相关的 doctest 块可以通过jldoctest关键字后的同名标签共享状态。Julia 手册就用这种模式演示可变mutation与重绑定rebinding的区别jldoctest mutation_vs_rebind julia a [1,2,3] ... jldoctest mutation_vs_rebind julia a[1] 42 ... 同名代码块在 doctest 运行时按顺序执行第一个块中创建的变量在后续块中仍然可用。当某个片段的计算结果需要在后续示例中继续使用时给它们加上相同标签即可这样既避免重复 setup 代码也更贴近真实 REPL 会话的行为。2.4 语法版本化syntax 当文档涉及新 Julia 语法时可用syntax 选项为 doctest 指定所需语法版本jldoctest; syntax v1.14 julia result label myblock begin for i in 1:10 i 5 break myblock i * 2 end 0 end 12 这保证代码块按指定语法版本解析即使文档是用更老的默认语法构建的新语法特性的 doctest 也能通过。对于以新语法为主的模块可在元块中设置全局默认值meta DocTestSyntax v1.14 单块的syntax 设置会覆盖全局DocTestSyntax。注意doctest 的语法版本化需要 Julia 1.14 及以上在更老的 Julia 上运行时syntax v1.14及以上的代码块会被跳过并给出警告。仓库的构建脚本正是通过meta Dict(:DocTestSyntax VERSION)将当前版本注入文档构建的见 doc/make.jl。三、验证流程每次 doctest 改动必须执行技能文档强调只要修改了任何jldoctest块就必须验证。验证步骤如下。第 1 步回顾最佳实践再次阅读 doc/src/devdocs/contributing/jldoctests.md特别确认改动的 doctest 是否需要 filters、labels 或 setup code。第 2 步运行 doctest提供两种运行方式按偏好选择使用预构建的 juliaup 版本运行make -C doc doctesttrue revisetrue JULIA_EXECUTABLE$HOME/.juliaup/bin/julia使用仓库内构建的 Julia 运行推荐make -C doc doctesttrue revisetrue这是首选方式且不要传递其他任何选项。⏱️ 重要提醒doctest 运行可能需要长达15 分钟。在完成之前不要终止doctest也不要为其设置超时例如在使用 ChatGPT 这类工具时可能需要调大yield_timeout_ms。3.1 命令背后的构建机制上述命令的含义可以从 doc/Makefile 中得到印证echo To run doctests, use make target doctesttrue echo To fix outdated doctests, use make target doctestfix echo To run doctests using Revise (to test changes without rebuilding the sysimage), use make target doctesttrue revisetruedoctesttrue开启 doctest 检查模式doctestfix自动修复过期的 doctest 输出直接改写文档中与运行结果不符的代码块输出需人工确认改动是否符合预期revisetrue借助 Revise 机制在不重新构建 sysimage 的情况下测试对源码的修改显著缩短迭代周期JULIA_EXECUTABLE...指定实际执行 doctest 的 Julia 可执行文件便于使用系统安装的 juliaup 版本。这些开关在 doc/make.jl 中被转换为 Documenter.jl 的doctest参数命令行含doctestfix时为:fix含doctestonly时为:only含doctesttrue时为true否则为false。其中doctestonly模式仅运行 doctest 而不构建完整文档适合快速回归。四、仓库中的真实案例佐证jldoctest并非孤立机制而是深度嵌入 Julia 主仓库的文档体系base/ 源码几乎所有 docstring 都包含 doctest例如 base/abstractarray.jl47 处、base/abstractdict.jl12 处等覆盖了过滤器、标签、多行正则等各类写法是学习jldoctest语法的最佳活教材。文档章节完整规范收录在 doc/src/devdocs/contributing/jldoctests.md并作为 Contributors Guide 的一部分被 doc/make.jl 注册到文档导航中。Agent 技能体系doctests 技能与 test-changes、c-static-analysis、external-deps 等技能共同构成 Julia 的 Agentic Devdocs 体系见 doc/src/devdocs/agents/README.md 与 doc/src/devdocs/agents/skills/doctests/SKILL.md。五、实操清单在提交任何涉及 doctest 的改动前对照以下清单自查编写阶段新写或修改jldoctest前复习 jldoctests.md判断需求输出是否可能变化内存未初始化、随机数、计时、路径是否需要filter docstring 内的正则是否已双重转义组织代码是否需要setup /DocTestSetup/teardown 多个块需要共享状态时是否已使用相同标签是否涉及新语法syntax 执行验证使用推荐命令make -C doc doctesttrue revisetrue仓库内 Julia运行 doctest耐心等待最多等待 15 分钟期间不终止、不设超时若输出过期可改用doctestfix自动修复后人工核对。遵循这套流程既能保证文档示例长期可运行也能让 doctest 成为 Julia 仓库中值得信赖的“活文档”。【免费下载链接】juliaThe Julia Programming Language项目地址: https://gitcode.com/gh_mirrors/ju/julia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考