自动部署Javadoc到Github Pages

doc
, ,

需求

由于想开一个新坑，打算把项目通过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 Keys与Secrets

因为我们需要把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

参考文献