Lib.rs

语言无关的文档生成器。用 Rust 🦀 编写

Fundoc - 生成文档的正确方法。您可以在项目中的不同文件甚至不同技术中实现业务功能。Fundoc 可以合并所有这些功能的描述并将它们放在适当的文件中。

Fundoc 的主要目标

• 让您将所有文档与代码一起保留。将文档和代码分开会使支持项目变得更加困难。
• 使用与代码相同的版本控制工具为您的文档 进行版本控制。您的文档的版本应与源代码的版本相匹配，否则我们无法相信文档。
• 文档生成器应允许您从不同的文件类型 编写文档，如源代码文件（Rust、C++、TypeScript、Java、JavaScript、Ruby、Python 等）、规范文件（Alloy、TLA+ 等）、样式表文件（CSS、SCSS、QT 样式表等）、配置（JSON、TOML、YAML 等）。

为什么你应该使用它

如果您想将文档与代码同步，并能够在实现业务功能的地点描述不同的部分，您可以在源文件或其附近编写文档。

一个源文件，一个文档文件

您可以在一个特定的源文件中描述业务逻辑，并从中生成文档。这可以用于描述配置文件、在一个文件或组件中实现的功能等。您可以在此找到使用 Fundoc 描述 ESLint/Prettier 配置的示例 示例。

多个源文件，一个文档文件

您可以使用不同的编程语言在多个源文件中编写文档，同时仍然能够将所有文档放在一个文件中（每篇文章一个文件）。

您还可以使用 .md 文件结合源文件和 .fdoc.md 文件中的文档。在这种情况下，文章的名称将来自文件名。

它可以帮您保持文档的更新，并且只更改与您正在修改的代码相关的文档部分。团队成员也可以通过在源文件上生成的链接轻松找到文档部分。

顺便说一下，这里的文档是由Fundoc本身生成的，因此您可以检查它的工作原理。

安装

您可以通过执行此shell脚本来安装Fundoc：

curl -LSfs https://japaric.github.io/trust/install.sh | \
    sh -s -- --git daynin/fundoc

如果您是Rust开发者并且已经安装了Rust编译器，您可以从crates.io安装Fundoc。

cargo install fundoc

或者从发布页面手动下载。

如何使用

您可以通过执行fundoc --init命令并回答几个问题来创建一个配置文件。

所有Fundoc的参数在此处有描述。

要生成文档，请运行fundoc。

Fundoc支持mdBook，因此如果您想以mdBook格式生成文档，可以在您的配置文件中将mdBook: true设置为true。如果您想在项目中使用GitHub Pages并支持全文搜索，这可能很有用。

插件

您可以编写自己的插件来增强Fundoc的功能。为此，您可以简单地编写一个Lua插件，如下所示：

function transform(text)
  importMermaid = '<script type="module"> import mermaid from "https://cdn.jsdelivr.net.cn/npm/[email protected]/+esm"; mermaid.initialize({}); </script>'

  result = '<pre class="mermaid">' .. text .. '</pre>' .. importMermaid
e

了解更多关于插件！

使用Fundoc的公司/项目

• Space Twistie
• CSSSR
• Zaya Tracker

知道其他公司/项目吗？创建一个PR让我知道！

GitHub Action

您可以使用Fundoc的GitHub Action来自动化文档生成。

路线图

• 合并来自不同文件的文档。
• 支持不同文件类型。
• 从文档中创建到源文件的链接。
• 生成具有搜索文档能力的mdBook。
• 支持多仓库（收集来自不同仓库的所有文档片段）。
• 添加Mermaid支持
• 添加插件系统
• 为插件系统添加文件系统API
• 为插件系统添加FFI
• 支持Zettelkasten方法（可能）