Autodocs

.github/workflows/ci.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches-ignore:
       - 'main'
+      - 'docs'
 
 env:
   BUILDER_VERSION: v0.8.29
@@ -116,6 +117,17 @@ jobs:
           chmod a+x builder
           ./builder build -p ${{ env.PACKAGE_NAME }} --spec=downstream
 
+  # check that docs can still build
+  check-docs:
+    runs-on: ubuntu-20.04 # latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          submodules: recursive
+      - name: Check docs
+        run: |
+          sudo apt-get install -y doxygen
+          ./make-docs.py
 
   check-submodules:
     runs-on: ubuntu-latest

.github/workflows/docs.yml

@@ -0,0 +1,40 @@
+# Update the API documentation whenever the `main` branch changes.
+# This documentation lives in its own `docs` branch.
+name: docs
+
+on:
+  push:
+    branches:
+      - 'main'
+
+jobs:
+  update-docs-branch:
+    runs-on: ubuntu-20.04 # latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          submodules: recursive
+
+      - name: Update docs branch
+        run: |
+          sudo apt-get install -y doxygen
+          ./make-docs.py
+
+      - name: Commit
+        run: |
+          git config --local user.email "[email protected]"
+          git config --local user.name "GitHub Action"
+          git add --force docs/
+          git commit --message="update docs"
+
+      - name: Push to docs branch
+        uses: ad-m/[email protected]
+        with:
+          github_token: ${{ github.token }}
+          branch: docs
+          # Force push so that `docs` branch always looks like `main`,
+          # but with 1 additional "update docs" commit.
+          # This seems simpler than trying to cleanly merge `main` into
+          # `docs` each time.
+          force: true

.github/workflows/lint.yml

@@ -1,6 +1,10 @@
 name: Lint
 
-on: [push]
+on:
+  push:
+    branches-ignore:
+      - 'main'
+      - 'docs'
 
 jobs:
   clang-format:

.gitignore

@@ -1,9 +1,13 @@
 .idea
 .DS_Store
+.vscode
 
 #cmake artifacts
 dependencies
 _build
 build
 _build_*
 cmake-build*
+
+# docs are updated automatically by .github/workflows/docs.yml
+docs/