lmake_readme

版本：0.5.4 日期：2020-06-07 作者：Luciano Bestia
将 cargo.toml 数据包含到 md 中，然后将 md 文件的内容包含到 src/*.rs 文件中作为后续文档生成的文档注释。

首先我们希望在 readme.md 中包含一些 cargo.toml 的数据。为了避免版本、作者和描述等数据不同步。
然后我们希望在 lib.rs 或 main.rs 文件的文档注释中包含 readme.md。
然后使用 cargo doc 从这些文档注释生成文档。
我们希望与 cargo.toml 和 readme.md 完全同步。
但同时也足够灵活，可以排除不需要的内容，并精确选择包含的位置。
包含可以执行多次，它只会替换旧内容。
lmake_readme 二进制文件必须在包含 cargo.toml 文件的项目的根目录下执行。
它只适用于单个项目，不适用于工作空间。

安装

从 crates.io 安装
cargoinstall lmake_readme
然后您可以在每个 rust 项目目录中使用它。
执行实用工具不需要任何参数。
尝试使用 --help 手动检查是否在当前目录中工作
lmake_readme--帮助

开发

文档
https://lucianobestia.github.io/lmake_readme/
为开发准备的制作任务列表：构建、运行、文档、发布、...
清除;cargo make

将 cargo.toml 数据包含到 readme.md 中

在 md 文件中写入这些标记

1 [comment]: # (lmake_readme cargo.toml data start)
2 [comment]: # (lmake_readme cargo.toml data end)

lmake_readme 删除标记之间的旧行
并包含日期和 cargo.toml 数据
版本、作者、描述。

将 md 内容包含到 rs 文件的文档注释中

如果您不需要 md 文件的所有内容，可以通过添加这些标记来排除行

1 [comment]: # (lmake_readme exclude start A)  
2 [comment]: # (lmake_readme exclude end A)  

在 rs 文件中写入这些标记

1 // region: lmake_readme include "filename.md" //! A  
2 // endregion: lmake_readme include "filename.md" //! A  

lmake_readme 删除标记之间的旧行。
读取要包含的 md 文件名。排除最终行。

在每行之前添加文档注释符号，如标记中定义的那样。
包含rs文件中的标记之间的新行。

货物裂缝审查和建议

建议始终使用 cargo-crev
来验证每个依赖项的可信度。
请，传播这个信息。
在网络上使用此url来读取crate审查。示例
https://web.crev.dev/rust-reviews/crate/num-traits/

Makefile.toml中的任务

我使用 cargo make 来脚本重复命令序列。
在 Makefile.toml 中添加一个类似这样的任务

[tasks.doc]
description = "create docs from comments"
clear = true
dependencies = [
    "include-readme",
    "cargo-doc",
    "doc-copy",
]

[tasks.include-readme]
clear = true
private = true
description = "copy the content of readme.md into *.rs comments (for the docs)"
script= ["lmake_readme"]

[tasks.cargo-doc]
clear = true
private = true
description = "call cargo doc"
command="cargo"
args=["doc","--no-deps","--document-private-items"]

[tasks.doc-copy]
clear = true
private = true
description = "copy doc folder as docs (out of folder target), so it can be git committed"
script = [
    "\\rsync -avz --delete-after target/doc/*  docs/"
]

阅读example.md以查看更复杂的场景，其中包含更多的ms文件和排除行。

待办事项

使用marker_name在不同标记之间进行匹配。尚未实现。