如何将Rust项目文件夹内所有rustdoc注释编译为单个markdown文件

rustdoc模板能力说明 #

原生rustdoc目前没有内置类似JSDoc的可自定义Markdown输出模板系统，它的默认输出格式为HTML，无法直接通过原生cargo doc命令生成你需要的自定义结构Markdown文档。你可以通过生态工具+自定义脚本的组合实现需求，方案可无缝扩展到数十个Example目录场景。

实现方案 #

前置准备 #

先安装cargo-readme工具，用于提取单个Rust crate的顶层文档注释为Markdown格式：

cargo install cargo-readme

步骤1：编写批量生成脚本 #

在MY_EXAMPLES根目录创建批量处理脚本，自动遍历所有Example目录、提取注释并生成汇总README。

Windows系统脚本（存为generate_readme.bat）

@echo off
:: 清空并初始化README
echo # 项目示例汇总 > README.md
echo. >> README.md

:: 遍历所有Example_开头的目录
for /d %%d in (Example_*) do (
    :: 写入示例标题
    echo ### %%d >> README.md
    cd %%d
    :: 提取当前示例的顶层注释，过滤空行后追加到README
    cargo readme --no-title --no-license | findstr /r /v "^[[:space:]]*$" >> ../README.md
    echo. >> ../README.md
    cd ..
)

Mac/Linux系统脚本（存为generate_readme.sh）

#!/bin/bash
echo "# 项目示例汇总" > README.md
echo "" >> README.md

for dir in Example_*/; do
    dirname=${dir%*/}
    echo "### $dirname" >> README.md
    cd "$dirname"
    cargo readme --no-title --no-license | grep -v "^\s*$" >> ../README.md
    echo "" >> ../README.md
    cd ..
done

给脚本添加执行权限（Mac/Linux）：

chmod +x generate_readme.sh

步骤2：绑定到cargo doc命令（可选） #

如果需要执行cargo doc时自动生成README，可在MY_EXAMPLES根目录新建工作空间配置文件Cargo.toml：

[workspace]
# 自动匹配所有Example开头的子crate
members = ["Example_*"]

[alias]
# Windows使用以下配置
doc = "!cargo doc --workspace && generate_readme.bat"
# Mac/Linux替换为以下配置
# doc = "!cargo doc --workspace && ./generate_readme.sh"

配置完成后，你在MY_EXAMPLES根目录执行cargo doc，会自动完成所有示例的HTML文档生成+自定义格式README.md生成，新增任意数量的Example_X目录都不需要修改配置，自动适配。

内容的提问来源于stack exchange，提问作者ANimator120