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

WriterSide 自动编译并部署到GitPage

1. GitHub 创建空仓库

在 GitHub 创建一个空的仓库

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

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

git remote add origin [email protected]:demodeom/write-auto-test.git

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

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

3. WriteSide 创建项目

打开软件 WriteSide 创建项目

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

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

1. 编辑器左边的工具条， 切换到 project 图表
2. 文件展示方式 选择 Peoject Files
3. 创建自动 编译部署 配置文件 1. 在项目根目录 创建目录 .github2. 在 .github 目录下创建目录 workflows3. 在 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.jsonretention-days:7test: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

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'

官网文档错误的

env:INSTANCE:'Writerside/hi'ARTIFACT:'webHelpHI2-all.zip'DOCKER_VERSION:'241.18775'

5. 自动编译、部署

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

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

第一次提交代码

# 初始化 git 仓库git init

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

# 将所有修改过的文件添加到 缓存区gitadd.# 将本地修改的文件提交到本地版本库git commit -m'first commit'# 添加远程仓库地址git remote add origin [email protected]:demodeom/write-auto-test.git

# 将本地代码推送到远程仓库git push -u origin main

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

点击任务

first commit

， 可以看到具体的进度

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

项目访问地址规律

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

比如：

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