使用pkgdown和Travis CI持续部署软件包文档 _TravisCI

本文概述

问题
解决方案
步骤
参考文献

问题 pkgdown是一个R软件包, 可以为你自己的R软件包创建一个外观漂亮的网站。该程序包由Hadley Wickham和他的多产贡献者团队构建和维护, 可以解析你的程序包的文档文件和小插图, 并使用一个命令build_site()从中构建一个网站。这样的pkgdown生成的网站实际上就是这样。
pkgdown生成的html文件存储在docs文件夹中。如果你的源代码托管在GitHub上, 则只需将此文件夹提交到GitHub, 导航到GitHub存储库的” 设置” 面板, 并启用GitHub页面将docs文件夹托管在https：// < name_or_org> .github.io / < package_name> 。这非常容易, 而且是第一步。实际上, 这就是托管pkgdown的pkgdown内置网站的方式。
尽管流程很优雅, 但是这种方法还是有一些问题。首先, 你要提交自动生成的文件, 即使构建它们所需的源文件已经存储在软件包中。通常, 将自动生成的文件提交到存储库不是一个好习惯。如果你更新文档并提交更改而不在本地重新呈现pkgdown网站怎么办？你的回购文件将不同步, 并且pkgdown网站将不会反映最新的更改。其次, 没有简单的方法可以控制发布文档的时间。也许你想在master分支之外工作, 但是在完成CRAN版本和相应的GitHub版本之前, 你不想更新文档。使用提交docs文件夹的临时方法, 这将很乏味。
解决方案有一个针对这些问题的快速解决方案, 那就是使用Travis CI。 Travis CI是一个连续整合工具, 对开源项目免费。正确配置后, Travis将接管你对存储库所做的任何更改。对于R软件包, Travis通常用于自动运行单元测试电池, 并检查该软件包是否基于R的多个早期版本构建。但这还不是全部。 Travis还可以进行部署。在这种情况下, 我将向你展示如何设置Travis, 使其自动为你构建pkgdown网站, 并将Web文件提交到gh-pages分支, 然后GitHub将其用于托管你的软件包网站。要了解如何在生产环境中为R软件包设置它, 请查看GitHub上的testwhat软件包, 我们在srcmini中使用了该软件包对学生提交的内容进行评分并提供有用的反馈。在本教程中, 我将为教程包设置pkgdown, 这是srcmini的另一个开源项目, 以使你的博客具有交互性。
步骤转到https://travis-ci.org并链接你的GitHub帐户。
在你的Travis CI配置文件页面上, 为要为其创建文档的项目仓库启用Travis。下次你对GitHub项目进行更改时, 将通知Travis并尝试构建你的项目。以后再说。

文章图片
在你的R软件包的Description文件中, 将pkgdown添加到” 软件包的建议” 列表中。这样可以确保travis在构建/安装软件包时也将安装pkgdown, 以便我们将其用于构建网站。
在.gitignore文件中, 确保git忽略了整个docs文件夹：添加docs / *行。
将名称为.travis.yml的文件添加到你的仓库的根文件夹中, 内容如下：

language: rcache: packagesafter_success:- Rscript -e 'pkgdown::build_site()'deploy:provider: pagesskip-cleanup: truegithub-token: $GITHUB_PATkeep-history: truelocal-dir: docson:branch: master

这个配置文件很短, 但是它做了很多不同的事情。 Jeroen Ooms和Jim Hester维护了R包的默认Travis构建配置, 该配置可以为你提供很多便利。一个仅具有以下语言的Travis配置文件：r标签已经可以构建, 测试和检查软件包中的不一致之处。让我们来看看其他领域：

缓存：软件包告诉Travis缓存两次构建之间的软件包安装。如果你有某些软件包依赖性, 这将大大加快软件包的构建时间。
after_success告诉Travis, 当R CMD CHECK步骤成功时, 应该采取哪些步骤。在我们的案例中, 我们告诉Travis建立pkgdown网站, 该网站将在Travis服务器上创建一个docs文件夹。
最后, deploy要求Travis继续进行操作, 并将docs文件夹(local-dir)中的文件上传到GitHub页面, 这是通过provider：pages指定的。如果触发变更的变更发生在master分支上, 则on字段会告诉Travis执行此部署步骤。

有关设置的完整概述, 请访问此帮助文章。我们不必指定要将文档推送到的GitHub目标分支, 因为它默认为gh-pages。
注意, 部署步骤还具有一个github-token字段, 该字段带有一个环境变量。 Travis需要此密钥才能对gh-pages分支进行更改。要获得这些凭据并确保Travis可以找到它们：

转到你的GitHub个人资料设置, 并在” 开发人员设置” 标签下创建一个新的个人访问令牌(PAT)。给它一个有意义的描述, 并确保生成一个具有public_repo(对于公共软件包)或repo(对于私有软件包)范围的PAT。

文章图片

复制PAT并转到Travis存储库设置, 你可以在其中指定环境变量。确保将环境变量命名为GITHUB_PAT。

文章图片
现在就可以进行构建了！使用有意义的消息将对仓库(DESCRIPTION和.travis.yml)的更改提交给GitHub存储库的master分支。
会通知Travis并开始工作：它将构建软件包, 进行检查, 如果这些步骤成功, 它将构建pkgdown网站并将其上传到gh-pages。

文章图片
GitHub注意到已经创建了一个gh-pages分支, 并立即将其托管在https：// < name_or_org> .github.io / < package_name> 。在我们的例子中, 这是https://srcmini.github.io/tutorial。看一看。真漂亮！没有任何其他配置, pkgdown已建立了一个以GitHub README为主页的网站, 所有导出功能的完整概述, 并在” 文章” 部分下进行了渐晕。
从现在开始, 每次更新软件包的master分支并且软件包检查通过时, 你的文档网站将自动更新。你不再需要担心使生成的文件与实际的包装内文档和小插图保持同步。你还可以轻松地调整部署过程, 以便仅在发布GitHub版本时才构建文档。在此过程中, 你免费获得了R包的持续集成：下次进行更改时, Travis会通知你他们破坏了任何测试或检查。
【使用pkgdown和Travis CI持续部署软件包文档】包装愉快！
参考文献

pkgdown：https：//github.com/r-lib/pkgdown、https：//pkgdown.r-lib.org/。
测试方法：https：//github.com/srcmini/testwhat、https：//srcmini.github.io/testwhat。
教程：https：//github.com/srcmini/tutorial、https：//srcmini.github.io/tutorial。
有关使用Travis CI构建R项目的完整文档：https：//docs.travis-ci.com/user/languages/r/。
有兴趣参与testwhat内部吗？我们正在招聘一名软件工程师, 以进一步改善我们的自动检查和反馈生成, 并将srcmini确立为该领域的领先者。查看我们的工作清单！