自动部署Javadoc到Github Pages

需求

由于想开一个新坑,打算把项目通过Maven生成的的Javadoc使用 Github Actions 自动部署到同项目下 gh-pages 分支,作为该项目 Github Pages 的主页供其他人参考。

操作

1. 配置 Maven 生成JavaDoc

首先在项目的 pom.xml 中添加 Maven Javadoc Plugin ,依赖这个插件,我们可以自动生成JavaDoc。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.2.0</version>
<configuration>
<classifier>javadoc</classifier>
<detectJavaApiLink>true</detectJavaApiLink>
<encoding>UTF-8</encoding>
<charset>UTF-8</charset>
<docencoding>UTF-8</docencoding>
<!-- <locale>zh_CN</locale> 可选,使用中文的界面-->
</configuration>
<executions>
<execution>
<id>attach-javadocs</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
<plugins>

设置过后,我们就可以输入 mvn javadoc:javadoc 命令生成该项目的Javadoc了,生成的路径一般在 target/site/apidoc/ 下。

如果是使用的 mvn package 命令,则会生成在 target/apidoc/ 下。

2. 配置Github项目的Deploy KeysSecrets

因为我们需要把Javadoc放到同项目下的gh-pages分支,因此在Actions中需要进行认证操作,才可以正常推送。

这里我们打算采用SSH进行推送,并通过 Deploy Keys 进行认证。

a. 生成 OpenSSH 密钥

我们可以访问 Generate SSH Keys Online 在线生成一个密钥。

generate key

点击后,在下方会生成对应的私钥(Private Key)与公钥(Public Key),我们先记下。

b. 添加私钥到 Secrets

复制上一步得到的私钥,添加到项目的Secrets中。

add secret

名字(Name)填DEPLOY_PRI,数值(Value)填私钥内容

confirm secret

c. 添加公钥到 Deploy Keys

复制之前得到的公钥,添加到项目的Deploy Keys中。

add deploy key

名字(Title)可以随便填,我这里选择的是JAVADOC_DEPLOY,密钥(Key)填公钥内容。注意一定要勾选 “Allow write access”, 这样才可以被用于推送。

confirm deploy key

3. 配置 Github Actions

在项目下新建 .github/workflows/javadoc.yml 文件。这个文件会被自动识别为Github Actions配置文件。

记得也要在Settings中启用 Github Actions ,否则无法使用哦。

内容如下

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
name: Javadoc

on:
# 支持手动触发构建
workflow_dispatch:
release:
# 创建release的时候触发
types: [ published ]
# push: # 可选,在推送主分支时触发
# branches:
# - main
# - master

jobs:
apidoc-deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout the repo
uses: actions/checkout@v2

- name: Set up the Java JDK
uses: actions/setup-java@v2
with:
java-version: '11'
distribution: 'adopt'

- name: Generate docs #生成Javadoc
run: mvn javadoc:javadoc

- name: Copy to Location # 复制Javadoc到一个新文件夹,便于进行git操作
run: |
rm -rf docs
mkdir -vp docs
cp -vrf target/site/apidocs/* docs/

- name: Generate the sitemap # 可选,生成sitemap
id: sitemap
uses: cicirello/generate-sitemap@v1
with:
base-url-path: https://carmjos.github.io/userprefix
path-to-root: docs

- name: Configure Git # 配置Git
env:
DEPLOY_PRI: ${{secrets.DEPLOY_PRI}} # 这里就是刚刚配置的私钥了
GIT_USERNAME: ${{ github.repository_owner }} #Github用户名,这里用了Actions自带的变量,也可以写死。
GIT_EMAIL: ${{ github.repository_owner }}@user.github.com # 邮箱,可以写自己的邮箱。
run: |
sudo timedatectl set-timezone "Asia/Shanghai"
mkdir -p ~/.ssh/
echo "$DEPLOY_PRI" > ~/.ssh/id_rsa
chmod 600 ~/.ssh/id_rsa
ssh-keyscan github.com >> ~/.ssh/known_hosts
git config --global user.name '$DEPLOY_PRI'
git config --global user.email '$DEPLOY_PRI'


- name: Commit documentation # 提交文档到Git仓库
env:
GIT_URL: "git@github.com:<USERNAME>/<PROJECT>.git" # 项目的地址,注意要用SSH格式的。
run: |
cd docs
git init
git remote add origin $GIT_URL
git checkout -b gh-pages
git add -A
git commit -m "API Document generated."

- name: Push javadocs # 推送
run: |
cd docs
git push origin HEAD:gh-pages --force

随后,推送项目,在Actions界面找到该配置,手动触发一次。

run-action

等待其正常跑完,即可发现多了一个 gh-pages 分支。

4. 设置 Github Pages

在项目的Settings界面找到 Pages 一栏,选择 gh-pages 分支,点击 Save ,等待片刻即可访问 <用户名>.github.io/<项目名> 看到项目的Javadoc了。

Setting Pages.png

参考文献