github: workflow: docs: Push 'main' docs to gh-pages

Distinguish between pull requests, and pushes to 'main'.  The pull
request docs are published on s3, with a mechanism to retire those after
a time.

Pushes to 'main' (happens when code merges) replace the documentation on
gh-pages.  These are available for anyone wanting to see "the latest
docs".

Signed-off-by: David Brown <[email protected]>

docs: Add latest commit to top of index

Insert `git show --stat HEAD` into the template for the top-level docs,
to make it easy to see what a build was generated for.

Signed-off-by: David Brown <[email protected]>

Author: d3zd3z

.github/workflows/docs.yml

@@ -21,6 +21,7 @@ jobs:
         uses: actions/checkout@v4
         with:
           path: zephyr-lang-rust
+          fetch-depth: 0   # Ensure full history is available
 
       - name: Set up Python
         uses: actions/setup-python@v5
@@ -47,7 +48,6 @@ jobs:
           west build -t rustdoc -b qemu_cortex_m3 docgen
           mkdir rustdocs
           mv build/rust/target/thumbv7m-none-eabi/doc rustdocs/nostd
-          cp docs/top-index.html rustdocs/index.html
 
       - name: Build build documentation
         working-directory: zephyr-lang-rust
@@ -56,12 +56,25 @@ jobs:
           cargo doc
           mv target/doc ../rustdocs/std
 
+      - name: Inject commit details into top-level commit.
+        working-directory: zephyr-lang-rust
+        env:
+          COMMIT_SHA: "${{ github.event.pull_request.head.sha || github.sha }}"
+        run: python3 etc/add-hash.py
+
       - name: Upload docs artifact
+        if: github.event_name == 'pull_request'
         uses: actions/upload-artifact@v4
         with:
           name: rustdocs
           path: zephyr-lang-rust/rustdocs
 
+      - name: Upload pages artifact
+        if: github.event_name == 'push'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: zephyr-lang-rust/rustdocs
+
   doc-publish:
     name: Publish Rust Documentation
     needs: generate-docs
@@ -71,21 +84,11 @@ jobs:
       github.repository == 'zephyrproject-rtos/zephyr-lang-rust'
 
     steps:
-      # - name: Show github context
-      #   env:
-      #     GITHUB_CONTEXT: ${{ toJson(github) }}
-      #   run: |
-      #     echo "$GITHUB_CONTEXT" | jq .
-
       - name: Download documentation artifact
         uses: actions/download-artifact@v4
         with:
           name: rustdocs
 
-      # - name: Show our tree
-      #   run: |
-      #     find . -ls
-
       - name: Publish to S3
         env:
           AWS_ACCESS_KEY_ID: ${{ vars.AWS_BUILDS_ZEPHYR_LANG_RUST_PR_ACCESS_KEY_ID }}
@@ -94,3 +97,20 @@ jobs:
         run: |
           PR_NUM=${{ github.event.number || 'not-a-pr' }}
           aws s3 sync  --only-show-errors . s3://builds.zephyrproject.org/zephyr-lang-rust/pr/$PR_NUM/
+
+  gh-publish:
+    name: Publish main to gh-pages
+    needs: generate-docs
+    permissions:
+      pages: write
+      id-token: write
+
+    runs-on: ubuntu-24.04
+    if: |
+      github.event_name == 'push' &&
+      github.repository == 'zephyrproject-rtos/zephyr-lang-rust'
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/top-index.html

@@ -10,5 +10,8 @@ <h1>Documentation Index</h1>
         <li><a href="nostd/zephyr/index.html">zephyr crate Documentation</a></li>
         <li><a href="std/zephyr_build/index.html">zephyr_build support Documentation</a></li>
     </ul>
+    <pre>
+{{COMMIT}}
+    </pre>
 </body>
 </html>

etc/add-hash.py

@@ -0,0 +1,25 @@
+#! /usr/bin/env python
+
+import os
+import subprocess
+
+input = "./docs/top-index.html"
+output = "rustdocs/index.html"
+
+# Get the commit from github (otherwise, we are likely to just see a merge commit.  Default to HEAD
+# if not provided.)
+commit_sha = os.getenv("COMMIT_SHA", "HEAD")
+
+try:
+    commit_info = subprocess.check_output(["git", "show", "--stat", commit_sha], text=True)
+except subprocess.CalledProcessError as e:
+    print(f"Error getting commit info: {e}")
+    commit_info = "Error retrieving commit details.\n"
+
+with open(output, "w") as outfile:
+    with open(input, "r") as file:
+        for line in file:
+            if "{{COMMIT}}" in line:
+                outfile.write(commit_info)
+            else:
+                outfile.write(line)