html improvements and fixed pandoc version (#312)

Co-authored-by: Marc Lichtman <[email protected]>

.github/workflows/generate_docs.yml

@@ -28,13 +28,20 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
       - name: Install prereqs
-        run: sudo apt install python3-pip pandoc inkscape texlive-latex-extra -y
+        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
       - name: Rename to index.html
         run: mv sigmf-spec.html index.html
       - name: Setup Pages

.gitignore

@@ -6,3 +6,4 @@ sigmf-spec.log
 sigmf-spec.aux
 svg-inkscape/
 sigmf-spec.html
+main.css

additional_content.md

@@ -75,9 +75,8 @@ used to describe the relationships between multiple Recordings.
 Collections and multiple Recordings can be packaged for easy storage and 
 distribution in a SigMF `Archive`.
 
-% Will eventually replace with a nicer one made in drawio
 \begin{figure}[t]
-\includesvg{images/SigMFobjects.drawio.svg}
+\includesvg[width=400px]{images/SigMFobjects.drawio.svg}
 \centering
 \end{figure}
 

docs-generator.py

@@ -70,12 +70,12 @@ def gen_fields(doc, d):
 )  # \usepackage[, urlcolor=blue, linkcolor=red]{hyperref}
 
 # Colors
-doc.append(NoEscape("\\definecolor{lightgray}{RGB}{240,240,240}"))  # for `short code`
+doc.append(NoEscape("\\definecolor{mylightgray}{RGB}{240,240,240}"))  # for `short code`
 doc.append(NoEscape("\\definecolor{lightblue}{RGB}{240,240,255}"))  # for table rows
 
 # Custom commands
 doc.append(
-    NoEscape("\\newcommand{\\code}[1]{\\texttt{\colorbox{lightgray}{#1}}}")
+    NoEscape("\\newcommand{\\code}[1]{\\texttt{\colorbox{mylightgray}{#1}}}")
 )  # \\code{} displays using monospace font and light gray background
 doc.append(NoEscape("\\newcommand{\\nn}[0]{\\vspace{4mm}\\\\\\noindent}"))  # \\nn gives a new line with space and no indent
 
@@ -179,6 +179,36 @@ def gen_fields(doc, d):
 except subprocess.CalledProcessError as e:
     print(e)  # this seems normal to occur
 
+# Create CSS file
+css_string = """
+#TOC {
+    position: fixed;
+    width: 20em;
+    left: -1em;
+    top: 0;
+    height: 100%;
+    background-color: white;
+    overflow-y: scroll;
+    padding: 0;
+}
+#subsec\:TableofContents {
+    display: none;
+}
+body {
+    padding-left: 20em;
+}
+code {
+    color: #000;
+    font-family: monospace;
+    background: #f4f4f4;
+}
+tr:nth-of-type(odd) {
+    background-color:#f0f0ff;
+}
+"""
+with open("main.css", "w") as f:
+    f.write(css_string)
+
 # Generate HTML
 css_url = "https://cdn.jsdelivr.net/npm/[email protected]/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}".split())
+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())