From 7af04ee30d40e02e47bef4229bd823b541a0a352 Mon Sep 17 00:00:00 2001
From: Abhinav Gupta
Date: Thu, 21 Dec 2023 15:26:03 -0800
Subject: Add autodoc website

This adds a `zig build docs` step that builds the documentation website
and writes it to zig-out/docs.

It further includes a GitHub Workflow that publishes this website
to GitHub Pages. The GitHub Workflow is divided into two jobs:

- build: builds the documentation and uploads it
- publish: downloads the documentation and publishes it

These are separate jobs to minimize permissions available
to the build job.

This workflow runs on two events:

- after every push to master
- `workflow_dispatch`: this allows manually running the workflow
  from its *Actions* page if something went wrong

---

**Important pre-merge steps:**

If this PR is accepted, the following steps should be taken
before merging the PR:

1. Go to **Settings** for the repository
2. Select **Pages** on the left under *Code and automation*
3. Under *Build and deployment* set **Source** to **GitHub Actions**
4. Merge the PR.

If the steps are missed, the PR will merge just fine,
but the docs job will fail immediately on merge.
This can be remedied by following steps 1-3 above,
and either adding a new commit on master,
or manually firing the workflow from the Actions > API Reference page.
---
 .github/workflows/docs.yml | 47 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)
 create mode 100644 .github/workflows/docs.yml

(limited to '.github/workflows')

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..defe4e2
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,47 @@
+name: API Reference
+
+on:
+  push:
+    branches: [master]
+
+  # Allow manually starting the workflow.
+  workflow_dispatch:
+
+# If two concurrent runs are started,
+# prefer the latest one.
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+
+  build:
+    name: Build website
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: goto-bus-stop/setup-zig@v2.0.1
+      with:
+        version: master
+    - name: Build
+      run: zig build docs
+    - name: Upload
+      uses: actions/upload-pages-artifact@v2
+      with:
+        path: "zig-out/docs/"
+
+  publish:
+    name: Publish website
+    runs-on: ubuntu-latest
+    needs: build  # wait for build to finish
+    permissions:
+      # Request sufficient permissions to publish the website.
+      pages: write
+      id-token: write
+    steps:
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v3
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
-- 
cgit v1.2.3