build pdf from legacy-latex and generate web site

William DeMeo · William DeMeo · commit 03919cf4e3fe · 2025-05-23T15:08:25.000-06:00
1.  **PDF Jobs (`...-pdf`)**:
    * removed `uses: ./.github/workflows/build_artifact.yml`;
    * added build steps (Nix install, `fls-shake`, upload) directly into job;
    * Most importantly, there are now *two* checkout steps; the first checks out current branch (`master-markdown`); the second uses `sparse-checkout` to grab *only `src` directory* from `legacy-latex` branch and places it into workspace, overwriting `src` from `master-markdown`;
    * When `fls-shake` runs, it uses build environment from `master-markdown` (our `flake.nix`, etc.) but operates on legacy LaTeX source.

2.  **MkDocs Job (`mkdocs-site`)**:
    * new job runs only on pushes/PRs to `master-markdown`;
    * uses `_build` artifact from initial Agda compilation;
    * calls `nix develop .#markdown --command "cd _build/mkdocs/src &amp;&amp; mkdocs build --site-dir ../../../site"`;
    * resulting `site` directory is uploaded as new artifact named `mkdocs-site`.

3.  **Artifacts Job (`upload-artifacts`)**:
    * job now depends on new `mkdocs-site` job;
    * downloads the `mkdocs-site` directory along with all other artifacts and commits them to `*-artifacts` branch, integrating new website into existing artifact deployment process.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -2,12 +2,14 @@ name: Build and upload artifacts
 on:
   push:
     branches:
-    - master
+      # !!! now running on new markdown branch and legacy latex branch !!!
+      - master-markdown
+      - legacy-latex
   pull_request:
     branches:
-    - master
-  # For running the workflow manually - useful for branches without PRs, for
-  # which CI isn't run automatically
+      # !!! now targeting PRs against new markdown branch !!!
+      - master-markdown
+  # For running workflow manually (for branches w/o PRs, where CI isn't run automatically)
   workflow_dispatch:
 
 permissions:
@@ -45,17 +47,113 @@ jobs:
     with:
       target: hs
 
+  # !!! Build mkdocs site from markdown files !!!
+  mkdocs-site:
+    needs: [formal-ledger-agda]
+    # only run on master-markdown branch
+    if: ${{ github.ref == 'refs/heads/master-markdown' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main repository
+        uses: actions/checkout@v4
+      - name: Download agda _build artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: _build
+          path: _build
+      - name: Install Nix
+        uses: cachix/install-nix-action@v31
+        with:
+          nix_path: nixpkgs=https://github.com/NixOS/nixpkgs/archive/6c5963357f3c1c840201eda129a99d455074db04.tar.gz
+          extra_nix_config: |
+            trusted-public-keys = hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=
+            substituters = https://cache.iog.io https://cache.nixos.org/
+      - name: Build MkDocs site
+        run: |
+          # !!! change to mkdocs src directory first !!!
+          nix develop .#markdown --command "cd _build/mkdocs/src && mkdocs build --site-dir ../../../site"
+          # --site-dir places output in root for upload step
+      - name: Upload MkDocs site artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: mkdocs-site
+          path: site
+
+  # !!! MODIFIED PDF JOBS !!!
+  # We now inline build steps and check out 'legacy-latex' branch to ensure PDF is
+  # built from correct LaTeX source files.
+
   cardano-ledger-pdf:
     needs: [formal-ledger-agda]
-    uses: ./.github/workflows/build_artifact.yml
-    with:
-      target: cardano-ledger.pdf
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo with build scripts (e.g., master-markdown)
+        uses: actions/checkout@v4
+      - name: Replace src with legacy LaTeX sources
+        uses: actions/checkout@v4
+        with:
+          # check out legacy-latex branch
+          ref: 'legacy-latex'
+          # only get 'src' directory
+          sparse-checkout: |
+            src
+          sparse-checkout-cone-mode: false
+      - name: Download agda _build artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: _build
+          path: _build
+      - name: Install Nix
+        uses: cachix/install-nix-action@v31
+        with:
+          nix_path: nixpkgs=https://github.com/NixOS/nixpkgs/archive/6c5963357f3c1c840201eda129a99d455074db04.tar.gz
+          extra_nix_config: |
+            trusted-public-keys = hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=
+            substituters = https://cache.iog.io https://cache.nixos.org/
+      - name: Build the target cardano-ledger.pdf
+        run: |
+          nix develop .#default --command fls-shake --trace -j8 cardano-ledger.pdf
+      - name: Upload cardano-ledger.pdf artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: cardano-ledger.pdf
+          path: dist
 
   conway-ledger-pdf:
     needs: [formal-ledger-agda]
-    uses: ./.github/workflows/build_artifact.yml
-    with:
-      target: conway-ledger.pdf
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo with build scripts (e.g., master-markdown)
+        uses: actions/checkout@v4
+      - name: Replace src with legacy LaTeX sources
+        uses: actions/checkout@v4
+        with:
+          # check out legacy-latex branch
+          ref: 'legacy-latex'
+          # only get 'src' directory
+          sparse-checkout: |
+            src
+          sparse-checkout-cone-mode: false
+      - name: Download agda _build artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: _build
+          path: _build
+      - name: Install Nix
+        uses: cachix/install-nix-action@v31
+        with:
+          nix_path: nixpkgs=https://github.com/NixOS/nixpkgs/archive/6c5963357f3c1c840201eda129a99d455074db04.tar.gz
+          extra_nix_config: |
+            trusted-public-keys = hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=
+            substituters = https://cache.iog.io https://cache.nixos.org/
+      - name: Build the target conway-ledger.pdf
+        run: |
+          nix develop .#default --command fls-shake --trace -j8 conway-ledger.pdf
+      - name: Upload conway-ledger.pdf artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: conway-ledger.pdf
+          path: dist
 
   html:
     needs: [formal-ledger-agda]
@@ -64,9 +162,9 @@ jobs:
       target: html
 
   upload-artifacts:
-    # This job runs only if the workflow has not been manually dispached
+    # run only if workflow has not been manually dispached
     if: ${{ github.event_name != 'workflow_dispatch' }}
-    needs: [formal-ledger-agda, hs, conway-ledger-pdf, cardano-ledger-pdf, html]
+    needs: [formal-ledger-agda, hs, conway-ledger-pdf, cardano-ledger-pdf, html, mkdocs-site]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -77,17 +175,15 @@ jobs:
         run: |
           printf "Set the artifacts branch name.\n"
           if [[ -n "${{ github.event.pull_request.head.ref }}" ]]; then
-            printf "This workflow was triggered by a PR to master\n"
+            printf "This workflow was triggered by a PR to master-markdown\n"
             echo "artifacts_branch=${{ github.event.pull_request.head.ref }}-artifacts" >> $GITHUB_OUTPUT
             printf "artifacts_branch: %s\n" "${{ github.event.pull_request.head.ref }}-artifacts"
           else
-            printf "This workflow was triggered by a push event to master\n"
-            echo "artifacts_branch=master-artifacts" >> $GITHUB_OUTPUT
-            printf "artifacts_branch: %s\n" "master-artifacts"
+            # Changed default artifact branch to master-markdown-artifacts.
+            printf "This workflow was triggered by a push event\n"
+            echo "artifacts_branch=master-markdown-artifacts" >> $GITHUB_OUTPUT
+            printf "artifacts_branch: %s\n" "master-markdown-artifacts"
           fi
-      # Checkout env.artifacts_branch if it already exists
-      # otherwise create a new orphan branch.
-      # Lastly, remove all files from the repo
       - name: Checkout artifacts branch
         run: |
           if [[ -n "$(git ls-remote --heads origin "${ARTIFACTS_BRANCH}")" ]]; then
@@ -113,30 +209,30 @@ jobs:
            <meta name="Author" content="IOHK">
            <title>Formal Ledger Specifications</title>
            <style type="text/css">
-            BODY { font-family : monospace, sans-serif;  color: black;}
-            P { font-family : monospace, sans-serif; color: black; margin:0px; padding: 0px;}
-            A:visited { text-decoration : none; margin : 0px; padding : 0px;}
-            A:link    { text-decoration : none; margin : 0px; padding : 0px;}
-            A:hover   { text-decoration: underline; background-color : yellow; margin : 0px; padding : 0px;}
-            A:active  { margin : 0px; padding : 0px;}
-            .VERSION { font-size: small; font-family : arial, sans-serif; }
+             BODY { font-family : monospace, sans-serif;  color: black;}
+             P { font-family : monospace, sans-serif; color: black; margin:0px; padding: 0px;}
+             A:visited { text-decoration : none; margin : 0px; padding : 0px;}
+             A:link    { text-decoration : none; margin : 0px; padding : 0px;}
+             A:hover   { text-decoration: underline; background-color : yellow; margin : 0px; padding : 0px;}
+             A:active  { margin : 0px; padding : 0px;}
+             .VERSION { font-size: small; font-family : arial, sans-serif; }
            </style>
           </head>
           <body>
           	<h1>Directory Tree</h1><p>
           EOF
 
-          tree -H '.'                     \
-               -L 1                       \
-               --dirsfirst                \
-               --hintro=/dev/null         \
-               --houtro=/dev/null         \
-               --metafirst                \
-               --charset utf-8            \
-               --timefmt '%d-%b-%Y %H:%M' \
-               -I "index.html"            \
-               -I "hs"                    \
-               -h -D --du                 \
+          tree -H '.'                          \
+               -L 2                            \
+               --dirsfirst                     \
+               --hintro=/dev/null              \
+               --houtro=/dev/null              \
+               --metafirst                     \
+               --charset utf-8                 \
+               --timefmt '%d-%b-%Y %H:%M'      \
+               -I "index.html"                 \
+               -I "hs"                         \
+               -h -D --du                      \
                >> index.html
 
           cat << EOF >> index.html
@@ -147,14 +243,13 @@ jobs:
           </body>
           </html>
           EOF
-
       - name: Commit artifacts
         run: |
             git config user.name 'github-actions[bot]'
             git config user.email 'github-actions[bot]@users.noreply.github.com'
             git add -A
-            git commit -m "Artifacts generated from ${{ github.sha }}"
-      - name: Push ${{ env.artifacts_branch }}
+            git commit --allow-empty -m "Artifacts generated from ${{ github.sha }}"
+      - name: Push ${{ steps.set-artifacts-branch.outputs.artifacts_branch }}
         uses: ad-m/github-push-action@v0.6.0
         with:
             github_token: ${{ secrets.GITHUB_TOKEN }}
