rust生成html文档

cci
317 阅读3分钟

在docs.rs看到的文档基本都是由这种方式生成的 docs.rs/

1、Rust原生生成

如果你写的是lib crate，可以用以下命令生成文档

rustdoc src/lib.rs
  • --crate-name docsname 设置包名

文档会生成在target\doc\位置

为Markdown文件生成文档

rustdoc README.md

README.md

# 好不好玩

# 太好玩了

执行命令rustdoc README.md会在根目录的doc文件夹生成文档README.html

2、Cargo生成（推荐）

cargo 内置了rustdoc，执行以下命令生成文档，默认将当前crate及其所有依赖的crate文档加进来

cargo doc
  • --open 用默认浏览器打开文档，后面指定文件名
  • --no-deps 不为依赖构建文档
  • --document-private-items 文档中包含非公共部分，如果是lib crate默认启用
  • --manifest-path 默认根据Cargo.toml的清单，通过该参数可以指定为某个清单生成文档
  • --workspace cargo.toml中所有的成员
  • --no-default-features 排除指定了默认features的功能
  • --exclude 排除指定包
  • --verbose 启用更加详细的输出
  • --quiet 不输出日志信息
  • --crate-name
  • -o 指定文档输出的位置
  • -L 帮助 rustdoc 找到代码的依赖，如果项目有依赖，也会生成依赖的文档

语法规范

文档注释一般用于告诉他人提供了哪些API

1、//! outer文档

通常在root crate比如src/lib.rs标记，描述crate的用途

  • 每个文件只能在开头描述

在interface\src\lib.rs这个lib crate中

//! 应用程序的入口点，用于启动应用程序
pub mod api{
    pub mod api;
}
/// 为什么要多加一层apapter？
/// CQRS职责分离，这里的目的是为了将业务逻辑和HTTP请求处理解耦，使应用程序的核心逻辑更加清晰，易于测试和维护
/// 将从业务逻辑层获取的数据转换为适合接口（例如 HTTP 响应）的格式
/// 只关注如何与外部进行交互，而不涉及具体的业务逻辑的实现细节
pub mod adapter{
    pub mod handler;
}
/// 公共响应
pub mod common{
    pub mod response;
}
/// 路由
pub mod routers{
    pub mod user_routes;
    pub mod order_route;
}

cargo doc生成

注意要在当前项目根目录执行

image.png

2、/// inner文档

在结构体、函数、实现、函数内部任何你想标记的地方，整个程序细节描述，比如告诉别人函数应该怎么用

  • 支持Markdown语法
  • # Examples 标记一个标题，标题名随便起
    • # Panics 标记可能发生panics的函数
    • # Errors 标记可能返回错误的函数，描述可能导致错误的条件等信息
    • # Safety 标记可能有安全问题的函数，描述函数为什么不安全
use interface::api::api::{self};
/// 这里是main函数
/// # Example 
/// ```
/// 行不行啊
/// ```
fn main() {
    let start_err = api::start();
    println!("{:?}", start_err);
}

cargo doc生成

image.png

如果你使用了多个模块，使用pub关键字可以将子模块的文档加入

注意区分model(模块)和crate，每个lib crate中创建的文件并定义了mod的才是模块

image.png

image.png

cargo doc --no-deps生成文档

image.png

父项目cargo.toml配置

# 工作区依赖仅指定版本，serde = { workspace = true }才是真正导入
[workspace.dependencies]
domain = { path = "domain" }
application = { path = "application" }
infrastructure = { path = "infrastructure" }
interface = { path = "interface" }
migration = { path = "migration" }
common = { path = "common" }

[dependencies]
# 因为在父项目使用了interface的模块用于启动程序，所以要将依赖导入
interface = { workspace = true }

在我的项目中有多个lib crate

  • cargo new的main.rs是binary crate
  • cargo new --lib的是lib crate

image.png

执行cargo doc --workspace --no-deps将cargo.toml工作区所有lib crate的文档导入

image.png

cargo doc --workspace --exclude migration --no-deps这次我们排除了migration这个lib crate

image.png

avatar
文章
阅读
粉丝