document caching (#119)

* document caching

* fix actions yaml

* ensure key is unique but also partially matched always

* shorten restore key

Author: chrisfenner

.github/workflows/docker-publish.yml

@@ -126,7 +126,8 @@ jobs:
             *.lof
             *.lot
             *.toc
-          key: latex
+          key: latex-${{ github.run_id }}
+          restore-keys: latex
 
       - name: Render for release
         uses: trustedcomputinggroup/markdown@latest

.github/workflows/render-samples.yml

@@ -68,7 +68,8 @@ jobs:
             *.lof
             *.lot
             *.toc
-          key: latex
+          key: latex-${{ github.run_id }}
+          restore-keys: latex
 
       - name: Run the action on guide
         uses: trustedcomputinggroup/markdown@latest

guide.md

@@ -101,26 +101,23 @@ Even if you used the template repository, please double-check this. As the tools
 are being actively developed, there is probably a newer version of the tools
 available for you!
 
-::: Caveat :::
+:::::::::::::::::::::::::::::::::::: Note :::::::::::::::::::::::::::::::::::::
 Use `ghcr.io/trustedcomputinggroup/pandoc:latest` at your own risk. As the tools
 may change defaults from version to version, it is better to pin your doc to
 a particular version of the tools and periodically update the tools as needed.
-::::::::::::::
+:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
 
-A typical Markdown-in-GitHub spec might want to automate the following:
+A typical GitHub Markdown repo will:
 
-* Render the spec to PDF on every pull request so that reviewers can check it.
-* Render the spec to PDF and Word on every release and attach to the release
-  page.
+* Render the spec to PDF on pull requests and attach the PDF to the PR.
+* Render the spec to PDF and Word on releases and attach them to the release.
+* Cache the LaTex intermediate files to the GitHub actions cache. This allows
+  small changes to the doc to render faster.
 
 `.github/workflows/actions.yml` might look a bit like this:
 
 ```yaml
-# Render the spec to PDF and Word on pull requests and releases, attaching the
-# outputs to the pull request / release, as appropriate.
-
 name: Render spec
-
 on:
   pull_request:
   release:
@@ -130,11 +127,28 @@ jobs:
   render:
     runs-on: ubuntu-latest
     container:
-      image: ghcr.io/trustedcomputinggroup/pandoc:0.8.2
-    name: Render PDF
+      image: ghcr.io/trustedcomputinggroup/pandoc:0.9.10
+    name: Render PDF and Word
     steps:
       - name: Checkout
         uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Cache LaTeX files
+        uses: actions/cache@v3
+        env:
+          cache-name: cache-latex-files
+        with:
+          path: |
+            *.aux
+            *.fdb_latexmk
+            *.lof
+            *.lot
+            *.toc
+          key: latex-${{ github.run_id }}
+          restore-keys: latex
 
       - name: Render
         uses: trustedcomputinggroup/[email protected]
@@ -150,13 +164,6 @@ jobs:
           name: spec.pdf
           path: spec.pdf
 
-      - name: Upload Word to PR
-        uses: actions/upload-artifact@master
-        if: ${{ github.event_name == 'pull_request' }}
-        with:
-          name: spec.docx
-          path: spec.docx
-
       - name: Upload PDF and docx to release
         uses: svenstaro/upload-release-action@v2
         if: ${{ github.event_name == 'release' }}
@@ -347,11 +354,11 @@ If you have GitHub Actions for rendering the spec for releases (see
 5.  A few minutes later, the PDF and DOCX of the spec will appear on the page
     for that release (you can monitor this on the "Actions" page).
 
-::: Tip :::
+:::::::::::::::::::::::::::::::::::: Note :::::::::::::::::::::::::::::::::::::
 When balloting or sending a document to the TC for review, please create a docx
 diff from Microsoft Word, comparing the docx outputs attached between releases
 with Word's "Compare Versions" tool.
-:::::::::::
+:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
 
 # Using Markdown
 
@@ -475,7 +482,7 @@ TCG uses a special visual style to demarcate informative non-binding remarks wit
 To create an informative note, use the following syntax:
 
 ```md
-::: Informative :::
+::::::::::::::::::::::::::::::::: Informative :::::::::::::::::::::::::::::::::
 This is the only informative text block in this document.
 
 These blocks can contain multiple paragraphs.
@@ -488,40 +495,42 @@ too large in an Informative Text block.
 | SPECIFICATION     | Usually                |
 | GUIDANCE          | Rarely                 |
 | REFERENCE         | Rarely                 |
-:::::::::::::::::::
+:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
 ```
 
 The above Markdown code becomes:
 
-::: Informative :::
+::::::::::::::::::::::::::::::::: Informative :::::::::::::::::::::::::::::::::
 This is the only informative text block in this document.
 
-These blocks can contain multiple paragraphs, tied together by lines containing just
-">".
+These blocks can contain multiple paragraphs, bulleted lists, etc.
 
-These blocks can even contain tables! However, be wary of providing tables that are
-too large in an Informative Text block.
+These blocks can even contain tables!
 
 | Document Type     | Informative Blocks     |
 | ----------------- | ---------------------- |
 | SPECIFICATION     | Usually                |
 | GUIDANCE          | Rarely                 |
 | REFERENCE         | Rarely                 |
-:::::::::::::::::::
+:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+
+Strictly speaking, three colons (`:::`) are the minimum required for marking
+an informative text block. However, it may make the plaintext version of the
+doc easier to read.
 
 ### Other Informative Blocks
 
 Writers of a document may prefer "informative" blocks with more specific
 semantics. In this case, the text is still contained within a "TCG Informative"
 gray box, but with a more meaningful header.
 
-::: Note :::
+:::::::::::::::::::::::::::::::::::: Note :::::::::::::::::::::::::::::::::::::
 This is a "Note" block.
-::::::::::::
+:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
 
-::: Example :::
+:::::::::::::::::::::::::::::::::: Example ::::::::::::::::::::::::::::::::::::
 This is an "Example" block.
-:::::::::::::::
+:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
 
 The behavior of blocks with labels not specified above may change meaningfully in future versions of this toolkit, so use them at your own risk.
 
@@ -995,10 +1004,10 @@ documents in Markdown:
     of a "Final" styled document. Note that according to the rules of semver, 1.23.5 is higher
     than 1.23.5-rc.1.
 
-::: Note :::
+:::::::::::::::::::::::::::::::::::: Note :::::::::::::::::::::::::::::::::::::
 If the spec is not rendered as part of a release, it will always be
 a draft, of some revision on top of the latest released version.
-::::::::::::
+:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
 
 ### Suppressing Git Version Parsing