Merge branch 'main' into bug/regex

.github/workflows/generate_docs.yml

@@ -46,10 +46,12 @@ jobs:
         run: pandoc -v
       - name: Rename to index.html
         run: mv sigmf-spec.html index.html
+      - name: Remove pandoc lib
+        run: rm -r pandoc*
       - name: Setup Pages
         uses: actions/configure-pages@v5
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v3.0.1
         with:
           path: '.' # Upload entire repository for now, TODO ONLY UPLOAD THE HTML AND PDF IN THE LONG TERM
       - name: Deploy to GitHub Pages

.github/workflows/generate_docs_pr.yml

@@ -1,4 +1,4 @@
-name: Build docs to check for errors
+name: Build docs [PR]
 
 on:
   pull_request:
@@ -29,3 +29,10 @@ jobs:
         run: ls -la
       - name: Check pandoc version
         run: pandoc -v
+      - name: Remove pandoc lib
+        run: rm -r pandoc*
+      - name: Upload output as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: compiled_docs
+          path: '.'

.gitignore

@@ -4,6 +4,8 @@ sigmf-spec.pdf
 sigmf-spec.out
 sigmf-spec.log
 sigmf-spec.aux
+sigmf-spec.fls
+sigmf-spec.fdb_latexmk
 svg-inkscape/
 sigmf-spec.html
 main.css

README.md

@@ -93,6 +93,8 @@ The main pdf is generated using the following content:
 
 The script `docs-generator.py` uses Python, PyLaTeX, Pandoc, and Inkscape to create the specifications document in PDF and HTML formats.
 
+Instead of generating the docs locally, you can make your change (e.g., using GitHub's web interface), open up a PR, and then under GitHub's "Actions" menu at the top, click the run that corresponds to your PR, scroll down to "Artifacts", download the artifact named "compiled_docs", unzip it, and you should be able to see the html and pdf.
+
 ## Frequently Asked Questions
 
 ### Is this a GNU Radio effort?

additional_content.md

@@ -160,16 +160,9 @@ The samples SHOULD be written to the Dataset file without separation, and the
 Dataset file MUST NOT contain any other characters (e.g., delimiters,
 whitespace, line-endings, EOF characters).
 
-Complex samples MUST be interleaved, with the in-phase component first (i.e.,
-`I[0]` `Q[0]` `I[1]` `Q[1]` ... `I[n]` `Q[n]`). When `core:num_channels` in the
-Global Object (described below) indicates that the Recording contains more than one channel,
-samples from those channels MUST be interleaved in the same manner, with
-the same index from each channel's sample serially in the Recording. For
-example, a Recording with two channels of `ri16_le` representing real-valued
-audio data from a stereo Recording and here labeled `L` for left and `R` for
-right, the data MUST appear as `L[0]` `R[0]` `L[1]` `R[1]` ... `L[n]` `R[n]`.
-The data type specified by `core:data_type` applies to all channels of data
-both real and imaginary parts.
+Complex samples MUST be interleaved, with the in-phase component first (i.e., `I[0]` `Q[0]` `I[1]` `Q[1]` ... `I[n]` `Q[n]`). 
+
+When `core:num_channels` in the Global Object (described below) indicates that the Recording contains more than one channel, samples from those channels MUST be interleaved in the same manner with the same index from each channel's sample serially in the Recording. This is intended for use in situations where the native SigMF datatypes are not appropriate, such as audio or oscilloscope channels. For best compatibility, is RECOMMENDED that native complex type datatypes be used whenever possible (e.g.: RF data).  The data type specified by core:data_type applies to all channels of data.  For multiple channels of IQ data (e.g., array processing), it is RECOMMENDED to use SigMF Collections.
 
 \subsection{SigMF Metadata Format}
 

docs-generator.py

@@ -1,6 +1,5 @@
 import json
 import subprocess
-import time
 
 from pylatex import (Command, Document, Figure, Package, Section, Subsection,
                      Subsubsection, Tabular)
@@ -35,7 +34,7 @@ def gen_table(table, d):
         dtype = value.get("type", "MISSING")
         # default = str(value.get("default", ""))
         longdescription = value.get("description", "")
-        shortdescription = longdescription[: longdescription.find(".")].replace("\n", "")  # short description, which is up to the first period
+        shortdescription = longdescription[: longdescription.find(". ")].replace("\n", "")  # short description, which is up to the first period followed by space
         table.add_row((field, required, dtype, shortdescription))
     table.append(NoEscape("\\bottomrule"))