codetour_export_to_md

版本：2020.605.1303 日期：2020-06-05 作者：Luciano Bestia
将 CodeTour 文件导出为 md 格式

CodeTour 是一个出色的 VSCode 扩展。向作者致敬。
https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour
每个 CodeTour 都包含步骤。
每个步骤都有一个描述和链接到源代码文件和行号的链接。
文档中不再有不同步的示例。
此类文档旨在用于代码流程说明。
以符合人类逻辑顺序的步骤逐步向其他程序员展示重要信息。
目前，此扩展仅在 VSCode 内部工作。这对其他编辑器的程序员来说是个问题。

markdown

在当前版本（2020-04-27）中，扩展没有导出到 markdown 文件的函数。
我在 VS Code 扩展和 TypeScript 方面的知识不足，无法提交 PR 贡献。
因此，我制作了一个 Rust 小型 CLI 程序。
我准备了这个项目作为“导出到 md”的一个概念证明。
生成的 md 文件非常好。它是一个文件，因此可以提交到 Github。
在 md 中有指向 Github 上源代码的链接。
这样所有程序员都可以在真实代码上跟随代码流程。

示例

我将我的其他项目中使用的几个文件复制到了 example/ 文件夹中。
有两个类似的 *.tour 文件。CLI 将导出该文件夹中的所有旅游文件。
如果没有任何参数，CLI 将查看标准 .tour/ 文件夹。
如果文件在其他文件夹中，例如我的示例中，参数如下
codetour_export_to_md 文件夹=示例/.tours

GitHub 和工作示例

在我其他项目中，我尝试编写一些关于代码流程的文档。
这很糟糕。
我避免了复制粘贴源代码，因为很快就会过时并具有误导性。
https://github.com/LucianoBestia/mem6_game/blob/master/CodeFlow.md
现在我已经从 CodeTour 导出了 md，真是太棒了
https://github.com/LucianoBestia/mem6_game/blob/master/codetour_start_route_template_render.md
逐步从模块跳转到模块的方法非常好。
它只是隐藏了其他所有非重要代码，便于人类基本理解代码流程。
链接是“活”的，它们会跳转到Github上的实际代码。

makefile.toml

我在创建类似这样的文档时使用它： makefile.toml：

[tasks.doc]
    description = "cargo doc - create docs from doc comments"
    clear = true
    script= [
        "echo $ lmake_readme",
        # copy data from cargo.toml to readme.md, then include text from readme.md into *.rs doc comments
        "lmake_readme",
        "echo $ cargo doc --no-deps --document-private-items",
        # create doc from doc comments
        "cargo doc --no-deps --document-private-items",
        "echo $ codetour_export_to_md",
        # export code tour to md
        "codetour_export_to_md",
        # copy to /docs/ because it is github standard
        "echo $ rsync -a --info=progress2 --delete-after target/doc docs",
        "rsync -a --info=progress2 --delete-after target/doc docs",
        # message to help user with next move
        "echo after successful doc, run cargo make fmt msg_for_commit",
        ]

安装

从crates.io安装
cargo安装codetour_export_to_md
无参数运行。最好与 cargo doc 一起使用。

开发

克隆仓库
git clone [email protected]:LucianoBestia/codetour_export_to_md.git
使用准备好的cargo make脚本
清除;cargo make release
清除;cargo make run_rel2
结果是
example/codetour_start_route_template_render.md