Skip to contents

开发人员引导

Source: vignettes/developer-guide.zh.Rmd
developer-guide.zh.Rmd

贡献

本项目目前处于积极开发阶段，非常欢迎各位参与和贡献。

为了保持对全球贡献者的包容性（inclusive），并确保讨论内容能够被尽可能多的开发者理解和维护，请在 issue、Pull Request 以及开发讨论中优先使用英语。

计算密集型文档

对于任何涉及实际计算和运行的 vignettes (文档)，例如涉及模拟的教程，请采用本地预编译的方式以加速 github pages 的构建过程。

每个文档的对应文件结构如下，例如，对于一个名为tutorial-a 的文档：

.
├── vignettes
│   ├── tutorial-a.Rmd.orig      # 预编译源文件（对于不涉及计算的文档可省略此文件）
│   ├── tutorial-a.Rmd           # 由源文件生成的最终文件
│   └── tutorial-a/              # 存放资源及预编译图片的子目录

本地预编译

首先，在 vignettes/ 目录下，将需要预编译的 Rmd 文件重命名为 *.Rmd.orig，例如 tutorial-a.Rmd.orig。

确保在该 Rmd 文件中，将图片路径配置到 vignettes/ 下的同名子目录，并偏好使用矢量图格式（如 SVG）以获得更好的缩放效果。一个示例配置如下：

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "./tutorial-a/",
  dev = "svg",
  fig.ext = "svg"
)

然后，在本地 R 环境中，运行下面代码中适合的那行以生成最终的 Rmd 文件：

# 在 R 环境中
source("scripts/knit_vignettes.R")

# 或在终端中
Rscript scripts/knit_vignettes.R

# 如果你需要全量编译所有脚本（不建议的）
Rscript scripts/knit_vignettes.R false

或，你可以手动修改并运行下面的代码片段以编译某一个特定的 Rmd 文件：

old <- getwd()
setwd("vignettes")

knitr::knit(
  "tutorial-a.Rmd.orig",
  output = "tutorial-a.Rmd"
)

setwd(old)

将文档加入 _pkgdown

一旦你完成了预编译过程，确保在 _pkgdown.yml 文件中正确引用了新的 Rmd 文件。例如：

articles:
- title: Tutorials
  navbar: Tutorials
  contents:
  - another-document
  - tutorial-a

提交更改

之后，你可以尝试在本地构建 pkgdown 网站以确保一切正常：

pkgdown::build_site()

确保所有内容均正确后，同时提交*.Rmd.orig 和生成的 *.Rmd。

此外，请不要手动修改生成的 *.Rmd 文件。我们应当假设这些文件是由对应的 *.Rmd.orig 文件自动生成的。