Improve some edge cases in cd-gh-pages.yml, e.g. when no gh-pages b…

…ranch exists yet. Refactor the `gh-pages` branch's readme to be generated by build-web-help.arc so that the whole GitHub Pages site is generated in one place. Fix the file path referred to in that readme.

.github/workflows/cd-gh-pages.yml

@@ -50,49 +50,59 @@ jobs:
         run: ./arc.sh -n build-web-help.arc
 
 
-      # We take the built `build-gh-pages` content from the `master` branch and
+      # We take the built dist/gh-pages/ content from the `master` branch and
       # deploy it as a commit to the `gh-pages` branch.
 
       # This is adapted from
       # <https://github.com/steveklabnik/automatically_update_github_pages_with_travis_example>.
 
       # We clone the `gh-pages` branch. If it doesn't exist yet, we create a new
       # branch with an empty history. Note that we authenticate using the
-      # `GITHUB_TOKEN` secret; this token is provided by GitHub to GitHub Actions
-      # workflows.
+      # `GITHUB_TOKEN` secret; this token is provided by GitHub to
+      # GitHub Actions workflows.
       - name: Clone the `gh-pages` branch, or create it with an empty history
         run: |
-          git clone "https://${{ github.actor }}:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git" build-gh-pages/repo
-          cd build-gh-pages/repo
+          git clone "https://${{ github.actor }}:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git" build/gh-pages-repo
+          cd build/gh-pages-repo
           git checkout gh-pages || git checkout --orphan gh-pages
 
-      # We replace all the files with the contents of the build-gh-pages/site/
-      # directory, plus a short readme. We stage all the files for a commit.
-      # (GitHub Actions workflows reset the working directory between steps, so
-      # we `cd` again.)
-      - name: Replace the `gh-pages` checkout's files with the built ones and a readme
+      # We replace the contents of the working directory with those of the built
+      # GitHub Pages site (first making sure that nothing would overwrite the
+      # .git/ directory). We stage all the files, including untracked ones.
+      #
+      # NOTE: The `cp -r path/. path` command syntax is based on:
+      #
+      #   https://stackoverflow.com/questions/14922562/how-do-i-copy-folder-wit
+h-files-to-another-folder-in-unix-linux
+      #
+      # We could also say `cp -r path/* path`, but it would fail if the source
+      # directory were empty.
+      #
+      - name: Stage a commit to `gh-pages` with the built GitHub Pages site
         run: |
-          cd build-gh-pages/repo
+          cd build/gh-pages-repo
           git rm -rf .
-          cp -r ../site/* .
-          cat > README.md <<EOF
-          This `gh-pages` branch is generated and deployed automatically when commits are made to the Anarki `master` branch. See the script .github/workflows/cd.yml on `master`.
-          EOF
+          test ! -e dist/gh-pages/.git
+          cp -r ../../dist/gh-pages/. .
+          git add -A .
 
-      # We stage all the files and make a commit to the `gh-pages` branch that
-      # looks a lot like the latest commit to `master`.
-      - name: Commit to `gh-pages`
+      # If there are any changes to commit, we make a commit to the `gh-pages`
+      # branch that looks a lot like the latest commit to `master`.
+      #
+      - name: Commit to `gh-pages` in a way that resembles the commit to `master`
         run: |
-          cd build-gh-pages/repo
+          cd build/gh-pages-repo
           git add .
           git config user.name "$(git log -1 --pretty=%an master)"
           git config user.email "$(git log -1 --pretty=%ae master)"
-          git commit -m "$(git log -1 --pretty=%B master)"
+          if [[ ! -z $(git status --untracked-files=no --porcelain) ]]; then
+            git commit -m "$(git log -1 --pretty=%B master)"
+          fi
 
       # We push this new commit to the `gh-pages` branch. We specify the remote
       # branch as `refs/heads/gh-pages` so that we create the branch if it
       # doesn't exist yet.
       - name: Push to `gh-pages`
         run: |
-          cd build-gh-pages/repo
+          cd build/gh-pages-repo
           git push -q origin HEAD:refs/heads/gh-pages

.gitignore

@@ -13,8 +13,10 @@ apps/managed/*
 
 www/
 
-# The build-web-help.arc script generates this directory.
-/build-gh-pages/
+# The build-web-help.arc script generates /dist/gh-pages/, for
+# deployment to GitHub Pages. Deliverables of other kinds could go
+# here too.
+/dist/
 
 # When `raco setup --package anarki` builds documentation, it goes
 # here.

build-web-help.arc

@@ -1,15 +1,17 @@
 ; build-web-help.arc
 ;
 ; Running this file executes the unit tests and then generates
-; build-gh-pages/site/help/index.html, a simple HTML file full of
+; dist/gh-pages/help/index.html, a simple HTML file full of
 ; docstrings.
 
 
 ; Load the docstrings by running the unit tests.
 (require 'tests.arc)
 
 
-(assign-and-warn web-help-dir* "build-gh-pages/site/help")
+(assign-and-warn gh-pages-dir* "dist/gh-pages")
+(assign-and-warn gh-pages-readme* (+ gh-pages-dir* "/README.md"))
+(assign-and-warn web-help-dir* (+ gh-pages-dir* "/help"))
 (assign-and-warn web-help-file* (+ web-help-dir* "/index.html"))
 
 (prn "Generating HTML documentation at " web-help-file* " ...")
@@ -44,7 +46,17 @@
               (tag (pre class "docstring-and-examples")
                 (pr:trim docstring)))))))))
 
+
 (ensure-dir web-help-dir*)
+
+(w/outfile out gh-pages-readme*
+  (w/stdout out
+    (prn:+
+      "This `gh-pages` branch is generated and deployed "
+      "automatically when commits are made to the Anarki `master` "
+      "branch. See the script .github/workflows/cd-gh-pages.yml on "
+      "`master`.")))
+
 (w/outfile out web-help-file*
   (w/stdout out
     (doctype "html")
@@ -157,4 +169,5 @@
             (display-web-help-section "Documented elsewhere"
               unknown-defs)))))))
 
+
 (prn "HTML documentation complete.")