如何为BOSL做贡献？docs_gen.py自动文档生成机制与Wiki编写指南

如何为BOSL做贡献docs_gen.py自动文档生成机制与Wiki编写指南【免费下载链接】BOSLThe Belfry OpenScad Library - A library of tools, shapes, and helpers to make OpenScad easier to use.项目地址: https://gitcode.com/gh_mirrors/bo/BOSLBOSLThe Belfry OpenScad Library是一个让 OpenSCAD 建模变得更简单、更高效的开源函数库汇集了数百个工具函数、常用形状与辅助模块。想让自己的代码被更多人使用最好的方式就是参与贡献。而BOSL最特别的一点是项目的官方 Wiki 文档并非手写而是由docs_gen.py自动文档生成机制从源码注释中批量产出的。也就是说你只要按规范写好注释Wiki 文档和示例图片就会自动生成。本指南将带你从零开始掌握 docs_gen.py 的自动文档生成机制与 Wiki 编写技巧成为 BOSL 的合格贡献者。一、BOSL 贡献的三种方式新手也能上手为 BOSL 做贡献并不一定要写复杂代码常见路径有三条修 Bug 与新增功能在shapes.scad、math.scad、transforms.scad等库文件中添加或修复模块与函数。编写测试项目在 tests/ 目录下维护了test_math.scad、test_convex_hull.scad等测试文件用assert校验函数正确性例如assert(quant(7,3) 6)。完善文档注释这是门槛最低、收益最高的方式因为文档会通过自动文档生成机制同步到 Wiki。无论选择哪条路你都需要理解 BOSL 的“注释即文档”哲学——这也是docs_gen.py存在的意义。二、docs_gen.py 自动文档生成机制是如何工作的从注释到 Wiki 的一键流水线scripts/docs_gen.py共 682 行是整套机制的核心引擎。它的工作流程可以概括为三个步骤解析注释扫描.scad文件中以//开头的结构化注释块识别LibFile、Section、Module、Function、Constant等关键词对应的语法规范详见 WRITING_DOCS.md。生成 Markdown把解析结果渲染成带目录、参数表格、示例代码的标准 Wiki 页面输出为xxx.scad.md文件。渲染示例图片把每个Example注释里的 OpenSCAD 代码拼装成临时.scad脚本调用本机 OpenSCAD 命令行渲染 PNG/GIF 图片再自动嵌入 Markdown。一张图看懂文档层次结构BOSL 源码注释 ├─ LibFile: shapes.scad → 库文件总览页 ├─ Section: Cuboids → 章节生成目录项 ├─ Module: cuboid() → 模块页含参数表示例图 ├─ Function: quant() → 函数页 └─ Constant: $fn → 常量页 │ ▼ docs_gen.py 解析渲染 输出 xxx.scad.md images/*.png │ ▼ 同步到项目 Wiki每个.scad库文件对应一个 Wiki 页面页面标题、目录树、参数表格全部由脚本自动排版贡献者无需关心 Wiki 的 Markdown 细节。命令行参数速查参数作用-c, --comments-only只处理//注释行-i, --images同时用 OpenSCAD 生成示例图片-I, --imgroot指定图片输出目录如images/shapes/-o, --outfile指定输出的 Markdown 文件名-k, --keep-scripts保留临时渲染脚本调试用三、Wiki 编写指南5 个必须掌握的关键词在 WRITING_DOCS.md 中定义了完整的注释格式。想写出能自动变成 Wiki 的注释只需记住下面 5 个关键词缩进是关键——通常注释内容需在//后至少缩进 3 个空格缩进结束即块结束。1. LibFile定义库文件主页每个.scad文件顶部都要声明自己的名字并附上使用说明例如 shapes.scad 开头的写法// LibFile: shapes.scad // Common useful shapes and structured objects. // To use, add the following lines to the beginning of your file: // // include BOSL/constants.scad // use BOSL/shapes.scad // 2. Section组织章节与目录用Section把相关的模块归组docs_gen.py会自动为每个 Section 生成目录条目和# 数字.编号标题// Section: Cuboids3. Module / Function参数表与示例的标配这是出现频率最高的注释块完整结构包括Usage用法、Description描述、Arguments参数表、Side Effects副作用和Example示例。以cuboid()为例// Module: cuboid() // Description: // Creates a cube or cuboid object, with optional chamfering or filleting. // Arguments: // size The size of the cube. // chamfer Size of chamfer, inset from sides. Default: No chamferring. // Example: Simple regular cube. // cuboid(40);脚本会把这些参数自动渲染成带参数名 | 作用表头的 Markdown 表格示例代码则会被自动缩进成代码块。4. CommonCode共享渲染代码如果多个示例需要重复的前置代码可以用CommonCode声明一次渲染示例图片时自动注入但不会显示在文档正文中非常适合定义text3d这类辅助模块。5. Constant一行注释即可收录常量可以不用完整注释块只要在代码行尾用// 描述注明即可被自动收录docs_gen.py中的正则^([A-Z_0-9]*) *.* // (.*$)会负责识别它们。四、示例标签让文档图片自动“活”起来docs_gen.py最酷的功能是根据Example(标签):中的标签自动决定渲染方式和图片格式详见 WRITING_DOCS.md2D / 3D选择俯视或斜视相机角度。Spin / FlatSpin让相机环绕物体旋转脚本会把 36 帧画面合成循环播放的GIF 动图-delay 25 -loop 0参数适合展示复杂零件全貌。FR强制完整渲染CGAL 模式而非预览模式。Small / Med / Big控制输出图片尺寸如480x360、800x600、1280x960。例如Example(FlatSpin):就会生成一张围绕 Z 轴旋转的动图直观展示零件的每个侧面。只要注释里写对标签图片自动生成、自动命名、自动嵌入贡献者几乎不需要碰任何图像处理工具。五、图片自动生成的完整流程临时脚本与图像对比当开启-i参数后docs_gen.py 会执行一条完整的图像流水线把公共代码和示例代码拼装成tmp_xxx.scad临时脚本调用OPENSCAD -o 输出.png --imgsize... --autocenter --viewall渲染用 ImageMagick 的convert调整尺寸若是 Spin 动图则合成 GIF用compare -metric MAE与旧图片做像素级对比图片无变化则不更新避免 Wiki 页面频繁变动。注意渲染依赖本机安装 OpenSCAD脚本中默认路径是 macOS 的/Applications/OpenSCAD.app/...和 ImageMagickWindows/Linux 用户需要自行修改这两个常量。六、一键批量生成make_all_docs.sh 脚本使用指南scripts/make_all_docs.sh是贡献者的“懒人利器”它会遍历constants、transforms、shapes、masks、beziers、math、threading等全部 20 个库文件逐个调用docs_gen.py生成文档与图片# 生成全部库文档 ./scripts/make_all_docs.sh # 只预览指定库如 shapes ./scripts/make_all_docs.sh shapes脚本要求从BOSL或BOSL.wiki目录运行生成的xxx.scad.md文件会直接放到 Wiki 仓库目录中图片则按images/库名/分类存放。跑完这条命令你就拥有了一份与官方 Wiki 完全一致的本地预览版。七、从注释到合入贡献者的最小流程克隆仓库git clone https://gitcode.com/gh_mirrors/bo/BOSL。编写代码与注释按 WRITING_DOCS.md 规范在对应的.scad文件中写好模块和注释。本地验证文档运行make_all_docs.sh 你的库名检查生成的 Wiki 页面与示例图片是否符合预期。运行测试用 OpenSCAD 打开 tests/test_math.scad 等测试文件确认所有assert通过。提交改动同时提交.scad源码和自动生成的.md文档、图片。八、给新贡献者的 5 条实用建议从Section和Description等纯文档贡献入手风险最低、上手最快每个Module至少配一个Example新手用户最需要“看得见的示例”参数默认值一定要写清楚如Default: V_CENTER它们会原样进入参数表格用Status: DEPRECATED, use BLAH instead.标记废弃功能脚本会自动把它们归入 Deprecations 章节修改注释缩进前先看一遍 WRITING_DOCS.md缩进错了会导致整块文档解析失败。九、总结为什么说“注释写得好贡献就成功了一半”BOSL 的docs_gen.py自动文档生成机制把文档维护从“写完代码再单独写文档”变成了“写注释就是写文档”。当你为shapes.scad、math.scad或任何库文件添加新功能时只要规范地写好注释官方 Wiki 页面、目录结构、参数表格、示例图片甚至旋转 GIF 都会自动更新。这不仅降低了贡献门槛也让文档永远和代码保持同步。现在就打开 WRITING_DOCS.md 和 docs_gen.py 开始你的第一次 BOSL 贡献吧【免费下载链接】BOSLThe Belfry OpenScad Library - A library of tools, shapes, and helpers to make OpenScad easier to use.项目地址: https://gitcode.com/gh_mirrors/bo/BOSL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考