使用fusen工具从Rmarkdown文件创建R包完整指南

什么是fusen项目

fusen是一个创新的R包开发工具，它采用"Rmarkdown优先"的开发理念，允许开发者通过编写Rmarkdown文档来构建完整的R包。这种方法将文档编写、函数开发、测试用例和包结构管理统一在一个工作流程中，大大简化了R包的开发过程。

快速开始：创建你的第一个fusen包

1. 初始化项目

使用fusen创建新包有两种方式：

方法一：通过RStudio界面

1. 打开RStudio
2. 选择 File > New Project > New directory > Package using {fusen}
3. 选择"teaching"模板开始

方法二：通过命令行

create_fusen("path/to/new/project", template = "teaching")

2. 理解模板结构

初始化后，项目中会生成一个"dev/flat_teaching.Rmd"文件，这是你的开发起点。这个文件包含几个关键部分：

• description部分：定义包的基本信息
• function部分：编写函数代码
• example部分：编写函数使用示例
• tests部分：编写单元测试
• development部分：开发配置代码

详细开发流程

1. 填写包描述信息

使用fill_description()函数设置包的元数据：

fill_description(
  pkg = dummypackage,
  fields = list(
    Title = "你的包标题",
    Description = "详细描述包的功能和用途",
    `Authors@R` = c(
      person("姓名", "姓氏", email = "邮箱", 
             role = c("aut", "cre"), 
             comment = c(ORCID = "ORCID号")),
      person(given = "公司", role = "cph")
    )
  )
)

2. 开发函数和文档

在Rmd文件中按以下结构组织内容：

```{r function-myfunction}
# 在这里编写你的函数代码
myfunction <- function(x) {
  # 函数实现
}
```

```{r example-myfunction}
# 函数使用示例
myfunction(1:10)
```

```{r tests-myfunction}
# 单元测试代码
test_that("myfunction works", {
  expect_equal(myfunction(1:10), expected_result)
})
```

3. 构建包

完成开发后，使用inflate()函数将Rmd转换为完整的包结构：

fusen::inflate(
  flat_file = "dev/flat_teaching.Rmd",
  vignette_name = "使用指南",
  open_vignette = TRUE,
  document = TRUE,
  check = TRUE
)

这个操作会：

1. 将函数代码移动到R/目录
2. 将测试代码移动到tests/testthat/目录
3. 将Rmd转换为vignette文档
4. 更新DESCRIPTION文件
5. 执行包检查

高级用法

添加新模板

当需要开发新功能模块时，可以添加新的模板文件：

add_flat_template(template = "add")
# 或简写
add_additional()

许可证设置

在development部分添加许可证信息：

```{r development-license, eval=FALSE}
usethis::use_mit_license("你的姓名")
```

最佳实践与注意事项

1. 命名规范：

   • 确保每个块名称唯一
   • 使用"function-前缀"命名函数块
   • 对应的示例和测试块使用"example-函数名"和"tests-函数名"

2. 开发流程：

   • 定期清除工作空间，避免环境变量干扰
   • 先写文档和示例，再实现函数(TDD理念)
   • 频繁执行inflate检查包结构

3. 限制说明：

   • 每个块通常对应一个主函数
   • 子函数可以放在同一个块中，但只有主函数能有示例
   • 示例和测试块必须放在对应函数块之后

为什么选择fusen

fusen的创新方法带来了几个显著优势：

1. 文档驱动开发：确保代码和文档同步更新
2. 简化流程：将多个开发步骤统一在一个界面中完成
3. 降低门槛：让新手更容易开始包开发
4. 可重复性：整个开发过程可完全重现

通过fusen，R包开发变得更加直观和高效，特别适合需要频繁迭代和文档更新的项目。无论是教学演示还是实际项目开发，fusen都能提供清晰的工作流和可靠的结果。