如何为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/BOSL

BOSL（The Belfry OpenScad Library）是一个让 OpenSCAD 建模变得更简单、更高效的开源函数库，汇集了数百个工具函数、常用形状与辅助模块。想让自己的代码被更多人使用？最好的方式就是参与贡献。而BOSL最特别的一点是：项目的官方 Wiki 文档并非手写，而是由docs_gen.py自动文档生成机制从源码注释中批量产出的。也就是说，你只要按规范写好注释，Wiki 文档和示例图片就会自动生成。本指南将带你从零开始，掌握 docs_gen.py 的自动文档生成机制与 Wiki 编写技巧，成为 BOSL 的合格贡献者。

一、BOSL 贡献的三种方式，新手也能上手

为 BOSL 做贡献并不一定要写复杂代码，常见路径有三条：

1. 修 Bug 与新增功能：在shapes.scad、math.scad、transforms.scad等库文件中添加或修复模块与函数。
2. 编写测试：项目在 tests/ 目录下维护了test_math.scad、test_convex_hull.scad等测试文件，用assert校验函数正确性，例如assert(quant(7,3) == 6)。
3. 完善文档注释：这是门槛最低、收益最高的方式，因为文档会通过自动文档生成机制同步到 Wiki。

无论选择哪条路，你都需要理解 BOSL 的“注释即文档”哲学——这也是docs_gen.py存在的意义。

二、docs_gen.py 自动文档生成机制是如何工作的？

从注释到 Wiki 的一键流水线

scripts/docs_gen.py（共 682 行）是整套机制的核心引擎。它的工作流程可以概括为三个步骤：

1. 解析注释：扫描.scad文件中以//开头的结构化注释块，识别LibFile、Section、Module、Function、Constant等关键词（对应的语法规范详见 WRITING_DOCS.md）。
2. 生成 Markdown：把解析结果渲染成带目录、参数表格、示例代码的标准 Wiki 页面，输出为xxx.scad.md文件。
3. 渲染示例图片：把每个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 细节。

命令行参数速查

三、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: Cuboids

3. 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.md：

• 2D / 3D：选择俯视或斜视相机角度。
• Spin / FlatSpin：让相机环绕物体旋转，脚本会把 36 帧画面合成循环播放的GIF 动图（-delay 25 -loop 0参数），适合展示复杂零件全貌。
• FR：强制完整渲染（CGAL 模式）而非预览模式。
• Small / Med / Big：控制输出图片尺寸（如480x360、800x600、1280x960）。

例如Example(FlatSpin):就会生成一张围绕 Z 轴旋转的动图，直观展示零件的每个侧面。只要注释里写对标签，图片自动生成、自动命名、自动嵌入，贡献者几乎不需要碰任何图像处理工具。

五、图片自动生成的完整流程：临时脚本与图像对比

当开启-i参数后，docs_gen.py 会执行一条完整的图像流水线：

1. 把公共代码和示例代码拼装成tmp_xxx.scad临时脚本；
2. 调用OPENSCAD -o 输出.png --imgsize=... --autocenter --viewall渲染；
3. 用 ImageMagick 的convert调整尺寸；若是 Spin 动图，则合成 GIF；
4. 用compare -metric MAE与旧图片做像素级对比，图片无变化则不更新，避免 Wiki 页面频繁变动。

注意，渲染依赖本机安装 OpenSCAD（脚本中默认路径是 macOS 的/Applications/OpenSCAD.app/...）和 ImageMagick，Windows/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 完全一致的本地预览版。

七、从注释到合入：贡献者的最小流程

1. 克隆仓库：git clone https://gitcode.com/gh_mirrors/bo/BOSL。
2. 编写代码与注释：按 WRITING_DOCS.md 规范，在对应的.scad文件中写好模块和注释。
3. 本地验证文档：运行make_all_docs.sh <你的库名>检查生成的 Wiki 页面与示例图片是否符合预期。
4. 运行测试：用 OpenSCAD 打开 tests/test_math.scad 等测试文件，确认所有assert通过。
5. 提交改动：同时提交.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