Sway 文档系统实战基于 mdBook 与 forc-documenter 预处理器构建 Forc 参考手册【免费下载链接】sway Empowering everyone to build reliable and efficient smart contracts.项目地址: https://gitcode.com/GitHub_Trending/sw/swaySway 语言官方书籍docs/book采用 mdBook 构建并依赖一个名为forc-documenter的自定义预处理器在每次构建时自动运行forc --help系列命令把 Forc 工具链的命令与插件帮助输出实时转成 Markdown 注入到书中。本文基于 docs/book/README.md 完整讲解本地构建流程并深入 scripts/mdbook-forc-documenter 的源码说明参考文档的自动生成、严格模式校验与章节维护规则读完即可独立完成 Sway 书籍的本地构建与 Forc Reference 章节的维护。书籍体系与配置结构书籍配置位于 docs/book/book.toml标题为The Sway Programming Language作者为 Fuel Labs[book] authors [Fuel Labs contactfuel.sh] language en multilingual false src src title The Sway Programming Language [output.html] git-repository-url https://github.com/FuelLabs/sway [preprocessor.forc-documenter] [rust] edition 2021其中[preprocessor.forc-documenter]是核心只要book.toml中存在这一节mdBook 每次构建都会执行该预处理器。书籍正文目录docs/book/src下的章节组织见 docs/book/src/SUMMARY.md其中与本文主题强相关的是Forc Reference部分它划分为Commands与Plugins两个章节Commands下逐条列出核心命令如forc add、forc build、forc check、forc contract-id、forc init、forc test等条目形如[forc build](https://link.gitcode.com/i/502efc055e3bf3d3d58896867f8ce620)Plugins下逐条列出插件如forc doc、forc fmt、forc lsp、forc migrate、forc publish、forc debug等并以子章节形式展开插件提供的多个子命令例如forc client下的forc deploy、forc run、forc submit、forc call。这些.md页面在仓库中只是占位文件——它们的真实内容是在构建时由预处理器注入的。从源码构建书籍依据 docs/book/README.md本地构建需要依次准备三类依赖1. 安装 mdBookcargo install mdbook官方建议安装后打开一个新的终端会话再执行后续命令。2. 安装 forc-documenter 预处理器预处理器源码就在仓库内scripts/mdbook-forc-documenter从仓库根目录执行cargo install --path ./scripts/mdbook-forc-documenter3. 安装书中已收录的 forc 插件预处理器通过 PATH 发现插件下文详述因此构建前必须安装书中已文档化的插件。README 给出的示例命令为cargo install --path ./forc-plugins/forc-client cargo install --path ./forc-plugins/forc-doc cargo install --path ./forc-plugins/forc-fmt cargo install --path ./forc-plugins/forc-lsp需要注意从当前仓库的 forc-plugins 目录结构看本仓库内实际包含的插件 crate 为forc-debug、forc-doc、forc-fmt、forc-lsp、forc-migrate、forc-publish、forc-tx而forc-client、forc-crypto、forc-node等章节对应的外部插件并不在本仓库中。README 也明确提示可以跳过即将被移除的插件、安装将被加入书籍的插件因此实际安装清单应以当前forc-plugins目录与SUMMARY.md中Plugins章节的交集为准。4. 构建与本地预览# 构建书籍 mdbook build docs/book # 严格模式构建检查 Forc Reference 中是否有页面需要增删 MDBOOK_preprocessor__FORC_documenter__STRICTtrue mdbook build docs/book # 本地服务预览 mdbook serve docs/book严格模式的实现逻辑在 scripts/mdbook-forc-documenter/src/lib.rs预处理器从自身配置中读取strict布尔值mdBook 会把MDBOOK_preprocessor__FORC_documenter__STRICT环境变量映射进配置树默认关闭。关闭时即使发现章节与工具链不一致也只向 stderr 打印警告并继续构建开启时则把同样的不一致转换为构建错误并终止构建。这正是 CI 场景与本地开发场景的分层策略——本地随时可构建CI 严格把关。forc-documenter 预处理器的工作原理预处理器入口是 scripts/mdbook-forc-documenter/src/lib.rs 中的ForcDocumenter结构体它实现了 mdBook 的Preprocessortraitname()返回forc-documenterL29-L31与book.toml中的[preprocessor.forc-documenter]段名对应supports_renderer仅对html渲染器生效L125-L127。run()方法L33-L128的执行流程如下解析 strict 开关读取配置中的strict项缺省为false枚举核心命令调用possible_forc_commands()执行forc --help解析Commands:到Options:之间的每一行取每行第一个词作为命令名scripts/mdbook-forc-documenter/src/commands.rs发现插件调用forc_plugins_from_path()执行forc plugins逐行解析以forc-前缀开头的条目得到插件名scripts/mdbook-forc-documenter/src/plugins.rs生成文档内容对每个命令/插件执行forc command --help合并 stdout 与 stderr逐行格式化为 Markdown见下文遍历书籍并注入内容book.for_each_mut遍历所有章节凡chapter.name Plugins或chapter.name Commands的章节把对应内容写入其子章节L51-L98。Commands章节还会额外把子章节索引形如- [forc build](https://link.gitcode.com/i/502efc055e3bf3d3d58896867f8ce620)的列表追加到章节末尾作为快速导航一致性校验构建完成后若存在工具链有、SUMMARY.md没有的缺失条目missing_entries_msg或SUMMARY.md有、工具链没有的悬空章节dangling_chapters_msgL138-L154按 strict 开关决定报错或警告。帮助输出到 Markdown 的格式规则generate_documentationcommands.rs负责把--help原始输出逐行转写具体规则集中在 scripts/mdbook-forc-documenter/src/formatter.rs原始行类型判定方式输出格式首行如forc-build索引为 0# forc-build一级标题子标题USAGE:/ARGS:/OPTIONS:/SUBCOMMANDS:命中SUBHEADERS常量表## USAGE:二级标题参数行PROJECT_NAME ...以开头_PROJECT_NAME_参数名加下划线斜体化描述另起一段选项行-o, --opt ...以-开头且次字符非空格-o _JSON_OUTFILE_选项加反引号、参数斜体化描述另起一段子命令行位于SUBCOMMANDS:之后clean独立成段描述跟随其他文本兜底原样保留这些规则均配有单元测试formatter.rs例如-c, --check选项行被格式化为-c, --check后跟描述段落。理解这张映射表后你在书中看到的 Forc 参考页面的排版结构标题、USAGE、ARGS、OPTIONS、子命令列表都能追溯到--help的原始输出。运行环境依赖预处理器有两个值得注意的环境假设插件发现依赖 PATHplugins.rs 的注释明确指出插件发现只在 Sway CI 的受控环境中可靠本地机器上 PATH 中有哪些插件构建出的书就可能不同。这就是为什么 README 要求先安装插件再构建。仓库根目录启发式定位find_sway_repo_rootlib.rs从当前目录逐级向上查找同时满足Cargo.toml、forc-plugins、scripts/mdbook-forc-documenter三个条件存在的目录以此定位 examples 目录scripts/mdbook-forc-documenter/examples/保证在仓库任意子目录下执行mdbook build都能工作。维护 Forc Reference 章节scripts/mdbook-forc-documenter/README.md 定义了文档与工具链同步的维护约定新增/删除 forc 核心命令新增时在SUMMARY.md的Commands章节下按以下格式加入条目- [forc fmt](https://link.gitcode.com/i/d33a0060aad43be0380f893daa281373)删除时直接移除该条目即可。条目名与--help输出的命令名必须严格对应——严格模式下缺失条目和悬空章节都会给出精确的修复提示测试用例见 lib.rs 中test_missing_entries_msg与test_dangling_chapters_msg报错信息会直接打印出应添加/应删除的条目文本。新增/删除 forc 插件步骤与核心命令相同但额外要求预处理器通过调用forc plugin --help生成文档所以插件二进制必须先安装进构建环境在 CI 中即为工作流里的安装步骤。删除插件时同样需要同步移除 CI 中的安装命令。为命令附加使用示例在scripts/mdbook-forc-documenter/examples/目录下新建一个以命令蛇形命名snake case命名的 Markdown 文件即可例如forc_build.md对应forc build。文件名与命令名的映射规则见get_forc_command_from_file_namecommands.rs取第一个.前的部分并把下划线替换为空格。预处理器在load_exampleslib.rs中加载全部示例并在inject_contentL130-L136把生成的帮助文档与匹配到的示例拼接到同一章节中。当前仓库已包含forc_build.md、forc_deploy.md、forc_init.md、forc_new.md、forc_migrate.md、forc_parse-bytecode.md、forc_template.md、forc_completions.md等示例文件可参考其写法。删除示例即删除对应文件。重命名章节的影响docs/book/README.md 最后特别警告Commands与Plugins这两个章节名是预处理器的匹配依据lib.rs中以chapter.name Plugins/chapter.name Commands精确匹配见 lib.rs 与 lib.rs。如果重命名SUMMARY.md中的章节名必须同步修改lib.rs中的匹配字符串否则对应章节的内容注入将静默失效非严格模式下甚至不会有报错。小结与验证方式整套文档管线的核心价值在于单一事实来源Forc 参考手册不再手写而是由forc --help的实际输出驱动SUMMARY.md只负责声明章节结构。本地可用MDBOOK_preprocessor__FORC_documenter__STRICTtrue mdbook build docs/book校验结构与工具链是否同步预处理器自身的行为则由lib.rs、commands.rs、formatter.rs中的单元测试覆盖可作为修改格式规则时的回归基线。如果你要动手扩展 Sway 书籍——新增一个插件章节、调整参考页排版或补充命令示例——以上文件就是全部需要理解的关键路径。【免费下载链接】sway Empowering everyone to build reliable and efficient smart contracts.项目地址: https://gitcode.com/GitHub_Trending/sw/sway创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考