ci(gha): New workflow to regen API docs on pushes to release branches

Upon pushing updates to files which may contain API documentation, the
workflow will regenerate the docs and, if there are relevant changes,
create a PR targeting the source branch.

[skip ci]

1 files changed, 51 insertions, 0 deletions

diff --git a/.github/workflows/api-docs.yml b/.github/workflows/api-docs.yml
new file mode 100644
index 0000000000..413c2e90c6
--- /dev/null
+++ b/.github/workflows/api-docs.yml
@@ -0,0 +1,51 @@
+name: Autogenerate API docs
+on:
+  push:
+    paths:
+      - 'src/nvim/api/*.[ch]'
+      - 'src/nvim/**.lua'
+      - 'runtime/lua/**.lua'
+    branches:
+      - 'master'
+      - 'release-[0-9]+.[0-9]+'
+  workflow_dispatch:
+
+jobs:
+  regen-api-docs:
+    runs-on: ubuntu-20.04
+    permissions:
+      contents: write
+      pull-requests: write
+    env:
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo env DEBIAN_FRONTEND=noninteractive apt-get install -y doxygen python3 python3-msgpack luajit
+
+      - name: Setup git config
+        run: |
+          git config --global user.name 'marvim'
+          git config --global user.email 'marvim@users.noreply.github.com'
+
+      - run: printf 'DOC_BRANCH=marvim/api-doc-update/%s\n' ${GITHUB_REF#refs/heads/} >> $GITHUB_ENV
+
+      - name: Generate docs
+        id: docs
+        run: |
+          git checkout -b ${DOC_BRANCH}
+          python3 scripts/gen_vimdoc.py
+          printf '::set-output name=UPDATED_DOCS::%s\n' $([ -z "$(git diff)" ]; echo $?)
+
+      - name: Automatic PR
+        if: ${{ steps.docs.outputs.UPDATED_DOCS != 0 }}
+        run: |
+          git add -u
+          git commit -m 'docs: regenerate'
+          git push --force https://${GITHUB_ACTOR}:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY} ${DOC_BRANCH}
+          gh pr create --fill --base ${GITHUB_REF#refs/heads/} --head ${DOC_BRANCH} || true