能否将roxygen2文档与函数分离存储？跨仓库托管是否可行？

嘿，让我来帮你理清这两个关于roxygen2的问题：

问题1：是否可以将roxygen2文档存储在与函数代码不同的文件中？ #

当然可以！虽然roxygen2的常规用法是把文档注释和函数定义放在同一个文件里，但它提供了灵活的方式来拆分两者。最实用的方法是借助@rdname标签来关联文档与函数：

• 先在单独的文件里只写roxygen2的文档注释块，结尾加上@rdname 你的函数名，最后放一个NULL（roxygen2需要解析文件里的R对象，NULL就是个合适的占位符）。
• 然后在函数所在的文件里，给函数也加上@rdname 同一个函数名标签（如果需要导出函数，@export标签放在文档文件里或者函数文件里都可以）。

举个实际的例子：

• 函数文件 R/calculate_double.R：

calculate_double <- function(x) {
  stopifnot(is.numeric(x))
  x * 2
}

• 文档文件 R/calculate_double_doc.R：

#' Calculate the double of a number
#'
#' Takes a numeric input and returns its doubled value.
#' @param x A numeric vector or scalar
#' @return The input multiplied by 2
#' @rdname calculate_double
#' @export
NULL

当你运行devtools::document()时，roxygen2会自动把这两个文件的内容关联起来，生成正确的.Rd文档文件到man/目录中。

问题2：将R包的文档托管在一个仓库，函数代码托管在另一个仓库，该方式通过roxygen2是否可行？ #

可行，但需要额外的构建流程来整合两个仓库的内容——毕竟roxygen2本身是基于本地文件系统解析文件的，没办法直接跨仓库读取内容。

具体的实现思路是这样的：

• 把函数代码单独放在一个仓库（比如命名为my-package-code），里面包含R/目录下的所有函数文件，以及包的核心配置文件（比如DESCRIPTION、NAMESPACE模板等）。
• 把分离的roxygen2文档文件放在另一个仓库（比如my-package-docs），文件结构最好和代码仓库的R/目录对应（直接放在R/目录下最容易被roxygen2识别）。

之后在构建包的时候，需要先把两个仓库的内容合并到同一个本地目录：

1. 克隆代码仓库到本地。
2. 克隆文档仓库，把里面的文档文件复制到代码仓库的R/目录下。
3. 运行devtools::document()生成man/目录下的正式文档。
4. 继续完成包的构建、检查等后续流程。

你可以用自动化工具简化这个过程，比如写个简单的shell脚本，或者用GitHub Actions、GitLab CI这类持续集成工具，让每次构建包时自动拉取两个仓库的内容并合并，再执行文档生成和构建步骤。

不过要提醒一句：这种分离方式会增加包维护的复杂度，比如修改函数后要同步更新对应文档仓库的内容，还要确保两个仓库的版本匹配。如果不是有特别强烈的需求，其实把代码和文档放在同一个仓库会更省心。

内容的提问来源于stack exchange，提问作者Ricardo Pietrobon