Rust文档生成工具库documented的使用指南

概述

documented是一个专为Rust项目设计的文档生成工具库，能够帮助开发者高效自动化地生成代码文档和API参考。该工具与Rust内置的rustdoc工具深度集成，提供了更丰富的自定义选项和自动化功能。

核心特性

• 自动化文档生成
• 支持Markdown格式
• 自定义文档模板
• API参考自动生成
• 代码示例验证
• 多格式输出支持（HTML、PDF等）

安装方法

在Cargo.toml中添加依赖：

[dependencies]
documented = "0.4.2"

或者使用cargo命令安装：

cargo add documented

基本使用方法

1. 基础配置

创建doc.toml配置文件：

[package]
name = "my-project"
version = "0.1.0"

[output]
format = "html"
directory = "./docs"

2. 生成文档

在项目根目录运行：

cargo documented

或者使用自定义配置：

cargo documented --config path/to/config.toml

3. 代码注释示例

/// 计算两个数字的和
///
/// # 示例
///
/// ```
/// use my_crate::add;
///
/// let result = add(2, 3);
/// assert_eq!(result, 5);
/// ```
///
/// # 参数
/// - `a`: 第一个加数
/// - `b`: 第二个加数
///
/// # 返回值
/// 返回两个参数的和
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

高级功能

自定义模板

[template]
path = "./custom_template"
variables = { project_name = "My Awesome Project" }

多模块支持

//! 主模块文档
//!
//! 这里可以写详细的模块说明

mod utils {
    //! 工具模块
    //!
    //! 包含各种实用函数
    
    /// 工具函数示例
    pub fn helper_function() {
        // 函数实现
    }
}

生成API参考

cargo documented --api-reference

配置选项详解

[output]
format = "html"        # 输出格式：html, markdown, pdf
directory = "./docs"   # 输出目录
theme = "dark"         # 主题选项

[processing]
include_private = false    # 是否包含私有项
warnings_as_errors = true  # 警告视为错误

[metadata]
authors = ["作者1", "作者2"]
repository = "https://github.com/username/repo"

集成到CI/CD

在.github/workflows/docs.yml中添加：

name: Generate Documentation

on:
  push:
    branches: [ main ]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Generate docs
        run: |
          cargo install documented
          cargo documented

最佳实践

1. 为所有公共API添加详细的文档注释
2. 包含代码示例并确保示例能够编译通过
3. 定期运行文档生成以确保文档与代码同步
4. 使用版本控制管理文档变更

故障排除

常见问题：

• 确保所有依赖项都已正确安装
• 检查配置文件格式是否正确
• 验证代码注释是否符合Rustdoc标准

通过合理使用documented库，可以显著提升Rust项目的文档质量，为团队协作和项目维护提供有力支持。

完整示例demo

以下是一个完整的Rust项目示例，展示如何使用documented库：

Cargo.toml

[package]
name = "math-utils"
version = "0.1.0"
edition = "2021"

[dependencies]
documented = "0.4.2"

src/lib.rs

//! 数学工具库
//!
//! 提供基本的数学运算函数

/// 计算两个数字的和
///
/// # 示例
///
/// ```
/// use math_utils::add;
///
/// let result = add(2, 3);
/// assert_eq!(result, 5);
/// ```
///
/// # 参数
/// - `a`: 第一个加数
/// - `b`: 第二个加数
///
/// # 返回值
/// 返回两个参数的和
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

/// 计算两个数字的差
///
/// # 示例
///
/// ```
/// use math_utils::subtract;
///
/// let result = subtract(5, 3);
/// assert_eq!(result, 2);
/// ```
///
/// # 参数
/// - `a`: 被减数
/// - `b`: 减数
///
/// # 返回值
/// 返回两个参数的差
pub fn subtract(a: i32, b: i32) -> i32 {
    a - b
}

/// 工具模块
pub mod utils {
    //! 实用工具函数
    
    /// 检查数字是否为偶数
    ///
    /// # 示例
    ///
    /// ```
    /// use math_utils::utils::is_even;
    ///
    /// assert!(is_even(4));
    /// assert!(!is_even(5));
    /// ```
    pub fn is_even(num: i32) -> bool {
        num % 2 == 0
    }
}

doc.toml

[package]
name = "math-utils"
version = "0.1.0"

[output]
format = "html"
directory = "./target/docs"
theme = "dark"

[processing]
include_private = false
warnings_as_errors = true

[metadata]
authors = ["开发者"]
description = "一个简单的数学工具库"

生成文档的命令

# 安装documented（如果尚未安装）
cargo install documented

# 生成文档
cargo documented

# 或者使用自定义配置文件
cargo documented --config doc.toml

# 生成包含API参考的文档
cargo documented --api-reference

GitHub Actions配置 (.github/workflows/docs.yml)

name: Generate Documentation

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Rust
        uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
          override: true
      - name: Generate documentation
        run: |
          cargo install documented
          cargo documented
      - name: Deploy to GitHub Pages
        if: github.ref == 'refs/heads/main'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./target/docs

这个完整示例展示了如何使用documented库来为一个数学工具库生成完整的文档，包括基本的配置、代码注释规范、以及CI/CD集成。