Rust文档生成工具wild-doc的使用，wild-doc助力快速创建高效、可定制的API文档与说明

Rust文档生成工具wild-doc的使用，wild-doc助力快速创建高效、可定制的API文档与说明

wild-doc示例

use wild_doc::*;

// 创建测试目录
let dir="./wd-test/";
if std::path::Path::new(dir).exists(){
    std::fs::remove_dir_all(dir).unwrap();
}
std::fs::create_dir_all(dir).unwrap();

// 初始化WildDoc实例
let mut wd = WildDoc::new(dir, Box::new(IncludeLocal::new("./include/")), None);

// 更新账户数据
let update_xml = br#"<wd:session name="account"><wd:update commit="true">
    <collection name="account">
        <field name="id">admin</field>
        <field name="password">admin</field>
    </collection>
</wd:update></wd:session>"#;
wd.run(update_xml, b"").unwrap();

// 使用JavaScript和模板生成文档
let r=wd.run(br#"<?js
    wd.general.test={a:1,b:2,c:3};
    console.log(wd.general.test);
?><wd:for
    var="aa" key="key" in:js="(()=>{return {a:1,b:2,c:3};})()"
><wd:print value:var="key" /> : <wd:print value:var="aa" />
</wd:for><wd:session name="logintest">
<wd:update commit="false">
    <collection name="login">
        <field name="test">hoge</field>
        <depend key="account" collection="account" row="1" />
    </collection>
</wd:update>
<wd:search
    collection="login"
><result
    var="login"
><wd:for var="row" in:var="login.rows"><wd:record var="row" collection="login" row:var="row">
    <wd:print value:var="row.row" /> : <wd:print value:var="row.uuid" /> : <wd:print value:var="row.field.test" /> : <wd:print value:var="row.depends.account" />
    <wd:search
        collection="account"
    ><row in:var="row.depends.account.row"><result
        var="account"
    ><wd:for var="a" in:var="account.rows"><wd:record var="a" collection="account" row:var="a">
        dep:<wd:print value:var="a.field.id" />@<wd:print value:var="a.field.password" />
    </wd:record></wd:for></result></wd:search>
</wd:record></wd:for></result></wd:search>
</wd:session>"#
    ,b""
).unwrap();
println!("{}", std::str::from_utf8(r.body()).unwrap());

// 清除会话
let update_xml = br#"<wd:session name="logintest" clear_on_close="true"></wd:session>"#;
wd.run(update_xml, b"").unwrap();

完整示例代码

use wild_doc::*;

fn main() {
    // 创建测试目录
    let dir = "./wd-test/";
    if std::path::Path::new(dir).exists() {
        std::fs::remove_dir_all(dir).unwrap();
    }
    std::fs::create_dir_all(dir).unwrap();

    // 初始化WildDoc实例
    let mut wd = WildDoc::new(
        dir, 
        Box::new(IncludeLocal::new("./include/")), 
        None
    );

    // 更新账户数据
    let update_xml = br#"<wd:session name="account"><wd:update commit="true">
        <collection name="account">
            <field name="id">admin</field>
            <field name="password">admin</field>
        </collection>
    </wd:update></wd:session>"#;
    wd.run(update_xml, b"").unwrap();

    // 使用JavaScript和模板生成文档
    let r = wd.run(br#"<?js
        wd.general.test = {a:1, b:2, c:3};
        console.log(wd.general.test);
    ?><wd:for var="aa" key="key" in:js="(()=>{return {a:1,b:2,c:3};})()">
        <wd:print value:var="key" /> : <wd:print value:var="aa" />
    </wd:for>"#, b"").unwrap();
    
    println!("{}", std::str::from_utf8(r.body()).unwrap());

    // 清除会话
    let update_xml = br#"<wd:session name="account" clear_on_close="true"></wd:session>"#;
    wd.run(update_xml, b"").unwrap();
}

包含文件示例

layout.xml

<html>
    <head>
        <title>HTML include test</title>
    </head>
    <body>
        <wd:include src:var="body_path" />
    </body>
</html>

body.xml

BODY

Rust代码

// 使用包含文件生成文档
let r = wd.run(br#"<wd:var body_path="body.xml">
    <wd:include src="layout.xml" />
<wd:var>"#, b"");
println!("{}", r);

输出结果

<html>
    <head>
        <title>HTML include test</title>
    </head>
    <body>
        BODY
    </body>
</html>

Python集成示例

在Cargo.toml中启用Python支持：

wild-doc = { version = "x", path = "../wild-doc", features = ["js", "py"] }

Python代码示例

// 使用Python脚本生成文档
let r = wd.run(br#"<?py
hoge = 100
def get_200():
    return 200
?><wd:print value:py="get_200()" />"#, b"").unwrap();

wild-doc是一个功能强大的Rust文档生成工具，支持JavaScript和Python脚本，提供灵活的模板系统，能够快速生成高效、可定制的API文档和说明。


1 回复

Rust文档生成工具wild-doc使用指南

wild-doc是一个强大的Rust文档生成工具，旨在帮助开发者快速创建高效、可定制的API文档和说明文档。

主要特性

  • 支持Markdown语法
  • 自动API文档生成
  • 高度可定制化
  • 支持文档主题切换
  • 与Rust生态无缝集成

安装方法

在Cargo.toml中添加依赖：

[dependencies]
wild-doc = "0.3"

或者通过cargo直接安装：

cargo add wild-doc

基本使用示例

生成项目文档

use wild_doc::generate;

fn main() {
    generate!(
        input: "./src",
        output: "./docs",
        theme: "dark"
    );
}

编写文档注释

/// # 计算两个数的和
/// 
/// ## 示例
/// 
/// ```rust
/// let result = add(2, 3);
/// assert_eq!(result, 5);
/// ```
/// 
/// @param a 第一个加数
/// @param b 第二个加数
/// @return 两个数的和
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

自定义文档配置

[project]
name = "My Awesome Project"
version = "0.1.0"
description = "一个使用wild-doc生成文档的示例项目"

[output]
directory = "docs"
theme = "light"
include_private = false

[extensions]
math = true
diagrams = true

高级功能示例

自定义主题

use wild_doc::Theme;

let custom_theme = Theme::new()
    .with_primary_color("#3498db")
    .with_font("Roboto")
    .with_layout("compact");

wild_doc::generate()
    .with_theme(custom_theme)
    .run();

集成测试示例

/// # 除法函数
/// 
/// ## 测试用例
#[cfg(test)]
mod tests {
    use super::*;
    
    /// 测试正常除法
    #[test]
    fn test_divide_normal() {
        assert_eq!(divide(10, 2), Ok(5));
    }
    
    /// 测试除以零
    #[test]
    fn test_divide_by_zero() {
        assert!(divide(10, 0).is_err());
    }
}

pub fn divide(a: i32, b: i32) -> Result<i32, String> {
    if b == 0 {
        Err(String::from("cannot divide by zero"))
    } else {
        Ok(a / b)
    }
}

完整示例Demo

下面是一个完整的wild-doc使用示例，包含项目结构、文档注释和配置：

  1. 首先创建项目结构：
my_project/
├── Cargo.toml
├── wild-doc.toml
└── src/
    ├── lib.rs
    └── main.rs
  1. Cargo.toml内容：
[package]
name = "my-project"
version = "0.1.0"
edition = "2021"

[dependencies]
wild-doc = "0.3"
  1. wild-doc.toml配置：
[project]
name = "My Project"
version = "0.1.0"
description = "wild-doc完整示例项目"

[output]
directory = "docs"
theme = "light"
include_private = true

[extensions]
math = true
  1. src/lib.rs内容：
//! 数学运算库
//!
//! 提供基本的数学运算功能

/// 加法运算
///
/// # 示例
///
/// ```
/// use my_project::add;
/// assert_eq!(add(1, 2), 3);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

/// 减法运算
///
/// @param a 被减数
/// @param b 减数
/// @return 差值
pub fn sub(a: i32, b: i32) -> i32 {
    a - b
}

/// 阶乘计算
///
/// ## 测试用例
#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_factorial() {
        assert_eq!(factorial(5), 120);
    }
}

/// 计算n的阶乘
pub fn factorial(n: u32) -> u32 {
    if n <= 1 {
        1
    } else {
        n * factorial(n - 1)
    }
}
  1. 生成文档：
cargo wild-doc --input ./src --output ./docs --theme light

生成的文档将包含所有公共API的说明、示例代码和测试用例，并采用light主题样式。文档可以部署到任何静态文件服务器。

回到顶部