Github action to check for docs generator build errors during PRs (#317)

* add github action for PRs

* apt update

* add apt update to main action too

* catch pandoc errors

* added pandoc error for testing

* remove test error

* ran black

* ran isort

---------

Co-authored-by: Marc Lichtman <marclichtman@microsoft.com>

.github/workflows/generate_docs.yml

@@ -27,6 +27,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+      - name: Apt update
+        run: sudo apt update
       - name: Install prereqs
         run: sudo apt install python3-pip inkscape texlive-latex-extra -y
       - name: Pip installs

.github/workflows/generate_docs_pr.yml

@@ -0,0 +1,31 @@
+name: Build docs to check for errors
+
+on:
+  pull_request:
+    # only runs on PRs that target main
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Apt update
+        run: sudo apt update
+      - name: Install prereqs
+        run: sudo apt install python3-pip inkscape texlive-latex-extra -y
+      - name: Pip installs
+        run: sudo pip install pylatex
+      - name: Install a more recent version of Pandoc than available from apt or pip (to get svg support)
+        run: |
+          wget "https://github.com/jgm/pandoc/releases/download/3.2/pandoc-3.2-linux-amd64.tar.gz"
+          tar -xvf pandoc-3.2-linux-amd64.tar.gz
+          sudo cp pandoc-3.2/bin/pandoc /usr/local/bin
+      - name: Build docs
+        run: python3 docs-generator.py
+      - name: Check if docs are generated
+        run: ls -la
+      - name: Check pandoc version
+        run: pandoc -v

docs-generator.py

@@ -1,8 +1,10 @@
-from pylatex import Document, Section, Subsection, Subsubsection, Package, Tabular, Figure
-from pylatex.utils import bold, NoEscape
 import json
-import time
 import subprocess
+import time
+
+from pylatex import (Command, Document, Figure, Package, Section, Subsection,
+                     Subsubsection, Tabular)
+from pylatex.utils import NoEscape, bold
 
 with open("sigmf-schema.json", "r") as f:
     data = json.load(f)
@@ -58,6 +60,7 @@ def gen_fields(doc, d):
 
 geometry_options = {"tmargin": "1in", "lmargin": "1in", "rmargin": "1in", "bmargin": "1in"}
 doc = Document(geometry_options=geometry_options)
+doc.preamble.append(Command("title", "SigMF"))  # doesn't actually show up anywhere, but was causing a warning when not included
 doc.packages.append(Package("underscore"))  # makes it so _ never means math mode!
 doc.packages.append(Package("xcolor", options=["table"]))  # allows for \rowcolors
 doc.packages.append(Package("listings"))
@@ -213,6 +216,12 @@ def gen_fields(doc, d):
 with open("main.css", "w") as f:
     f.write(css_string)
 
-# Generate HTML
+# Generate HTML from tex with Pandoc
 css_url = "https://cdn.jsdelivr.net/npm/bootstrap@4.4.1/dist/css/bootstrap.min.css"
-subprocess.run(f"pandoc sigmf-spec.tex -f latex -t html -s -o sigmf-spec.html --toc --toc-depth=3 -c {css_url} -c main.css".split())
+pandoc_out = subprocess.run(
+    f"pandoc sigmf-spec.tex -f latex -t html -s -o sigmf-spec.html --toc --toc-depth=3 -c {css_url} -c main.css".split(),
+    capture_output=True,
+    text=True,
+)
+if len(pandoc_out.stderr):
+    raise Exception("Pandoc error: " + pandoc_out.stderr)