ci: semi-automate cli docs generation

Adds a workflow that automates updating the CLI docs, opening a PR with the
updates for manual review. It's running against nightly versions right now just
as a POC, will switch it over to release versions once I'm happy that it works.

Author: slarse

.github/workflows/update-generated-docs.yml

@@ -0,0 +1,79 @@
+name: "Update Generated Docs"
+
+on:
+  workflow_dispatch:
+  schedule:
+    # every day at 2am UTC
+    - cron: "0 2 * * *"
+
+permissions: {}
+
+jobs:
+  update_generated_docs:
+    runs-on: ubuntu-latest
+    environment: Docs generation
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+
+      - run: |
+          git clone https://github.com/gitbutlerapp/gitbutler ../gitbutler
+
+      - name: Compare versions
+        id: versions
+        run: |
+          CURRENT_DOCS_VERSION=$(cat scripts/current_docs_version.txt)
+          LATEST_VERSION=$(git -C ../gitbutler tag --list 'nightly/*' --sort=-version:refname | head -n 1)
+
+          echo "Current: $CURRENT_DOCS_VERSION"
+          echo "Latest: $LATEST_VERSION"
+
+          test -n "$LATEST_VERSION"
+
+          echo "latest_version=$LATEST_VERSION" >> "$GITHUB_OUTPUT"
+
+          if [ "$LATEST_VERSION" != "$CURRENT_DOCS_VERSION" ]; then
+            echo "should_update=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "should_update=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Update generated docs
+        if: steps.versions.outputs.should_update == 'true'
+        env:
+          LATEST_VERSION: ${{ steps.versions.outputs.latest_version }}
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libdbus-1-dev libglib2.0-dev pkg-config
+
+          git -C ../gitbutler checkout "$LATEST_VERSION"
+          ./scripts/update-manpages.sh
+
+          echo "Updating scripts/current_docs_version.txt to $LATEST_VERSION"
+          echo "$LATEST_VERSION" > scripts/current_docs_version.txt
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          branch="update-generated-docs-$LATEST_VERSION"
+          git checkout -b "$branch"
+          git add .
+          git commit -m "Update CLI docs"
+          git push origin "$branch"
+
+          echo "branch=$branch" >> "$GITHUB_ENV"
+
+      - name: Create pull request
+        if: steps.versions.outputs.should_update == 'true'
+        run: |
+          gh pr create \
+            --title "Update generated CLI documentation for version ${LATEST_VERSION}" \
+            --body "Automatic docs update for ${LATEST_VERSION} @slarse @krlvi" \
+            --base main \
+            --head "$branch"
+        env:
+          GH_TOKEN: ${{ secrets.GH_CREATE_PR_PAT }}
+          LATEST_VERSION: ${{ steps.versions.outputs.latest_version }}

scripts/current_docs_version.txt

@@ -0,0 +1 @@
+nightly/0.5.2077

scripts/update-manpages.sh

@@ -38,7 +38,7 @@ rm -f cli-docs/*
 
 # Regenerate documentation using cargo
 echo "Regenerating CLI documentation with cargo..."
-cargo run --bin but-clap --features raw-clap-docs
+cargo run -p but-clap --bin but-clap --features raw-clap-docs
 
 echo "Documentation files regenerated successfully!"
 echo