WriterSide 文档、接口自动编译并部署到GitPage_writerside部署

1. GitHub 创建空仓库

在 GitHub 创建一个空的仓库

仓库创建成功后， 记录仓库的远程地址

仓库地址需要修改为自己的仓库地址， 比如我的仓库地址为

git remote add origin git@github.com:demodeom/write-auto-test.git
1

2. 配置GitHub 仓库的编译部署方式

设置仓库编译部署的方式为 GitHub Actions

3. WriteSide 创建项目

打开软件 WriteSide 创建项目

创建项目时， 项目存储目录 和 项目目录名可以自定义

4. 创建自动、编译部署配置文件

1. 编辑器左边的工具条， 切换到 project 图表
2. 文件展示方式 选择 Peoject Files
3. 创建自动 编译部署 配置文件
   1. 在项目根目录 创建目录 .github
   2. 在 .github 目录下创建目录 workflows
   3. 在 workflows 目录下创建文件 build-docs.yml
      

正确的 build-docs.yml 文件内容如下

name: Build documentation

on:
  push:
    branches: ["main"]
  workflow_dispatch:

permissions:
  id-token: write
  pages: write

env:
  INSTANCE: 'Writerside/in'
  ARTIFACT: 'webHelpIN2-all.zip'
  DOCKER_VERSION: '241.18775'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Build docs using Writerside Docker builder
        uses: JetBrains/writerside-github-action@v4
        with:
          instance: ${{ env.INSTANCE }}
          artifact: ${{ env.ARTIFACT }}
          docker-version: ${{ env.DOCKER_VERSION }}

      - name: Save artifact with build results
        uses: actions/upload-artifact@v4
        with:
          name: docs
          path: |
            artifacts/${{ env.ARTIFACT }}
            artifacts/report.json
          retention-days: 7
  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Download artifacts
        uses: actions/download-artifact@v4
        with:
          name: docs
          path: artifacts

      - name: Test documentation
        uses: JetBrains/writerside-checker-action@v1
        with:
          instance: ${{ env.INSTANCE }}
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: [build, test]
    runs-on: ubuntu-latest
    steps:
      - name: Download artifacts
        uses: actions/download-artifact@v4
        with:
          name: docs

      - name: Unzip artifact
        run: unzip -O UTF-8 -qq '${{ env.ARTIFACT }}' -d dir

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Package and upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: dir

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
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
73
74
75
76
77
78
79
80

build-docs.yml 文件内容模板可以在 官方文档找到， 官方文档地址 https://www.jetbrains.com/help/writerside/deploy-docs-to-github-pages.html

需要注意， 截止 2024 年 8 月 7 日， 官方文档提供的配置文件模板有两处错误

错误1： 默认的 instance_name 是 in ， 并不是文档上所说的 hi
错误2： ARTIFACT 文件名与 INSTANCE 的值相关， 所以也需要修改

修改正确的

env:
  INSTANCE: 'Writerside/in'
  ARTIFACT: 'webHelpIN2-all.zip'
  DOCKER_VERSION: '241.18775'
1
2
3
4

官网文档错误的

env:
  INSTANCE: 'Writerside/hi'
  ARTIFACT: 'webHelpHI2-all.zip'
  DOCKER_VERSION: '241.18775'
1
2
3
4

5. 自动编译、部署

代码推送到 GitHub 之后， 会自动编译部署

以下命令可以在 Writerside 终端执行

第一次提交代码

# 初始化 git 仓库
git init

# 修改当前分支名字为 main
git branch -M main

# 将所有修改过的文件添加到 缓存区
git add .

# 将本地修改的文件提交到本地版本库
git commit -m 'first commit'

# 添加远程仓库地址
git remote add origin git@github.com:demodeom/write-auto-test.git

# 将本地代码推送到远程仓库
git push -u origin main
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

代码推送到 GitHub 仓库后， 在 Action 页面可以看到，自动编译部署的进度

点击任务 first commit， 可以看到具体的进度

编译、部署完成之后， 可以看到项目地址，点击即可在线访问项目
不同的用户， 不用的项目， 访问地址不一样

项目访问地址规律

https://GitHub用户名.github.io/仓库名

比如：

• 用户名 demodeom
• 仓库名 write-auto-test
• 访问地址 https://demodeom.github.io/write-auto-test