SigMF Core JSON Schema and new method of creating HTML + PDF (#301)

* first cut

* remove high level default

* apply prettier

* misc edits

* making freq a realistic bound

* increase max sample rate

* rename file

* Added note in readme about validating using json schemas

* added collection json schema

* first cut of latex generated pdf

* added Antenna extension json schema

* moved diagram to images dir

* combined pre and post into one file

* fix link that had already been broken

* fixed url

* added antenna extension to pdf

* switched to nicer looking tables

* added svg

* pull version from json

* remove sigmf-spec.md to make it clear that this replaces it

* cleanups

* other updates that have been made since original PR

* make logo smaller

* update readme

* first attempt at pipeline

* run pipeline again

* dont deploy to pages for now

* remove pages persmissions

* disbale all github pages steps for now

* add sudo

* install texlive

* add ls to prove docs were generated

* get pipeline ready to run on main

* update link at start of readme to point to github pages

* remove antenna extension markdown, its replaced with the json schema

* ran black on docs-generator.py

* used index.html

---------

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

.github/workflows/generate_docs.yml

@@ -0,0 +1,48 @@
+name: Build docs and deploy static content to Pages
+
+on:
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install prereqs
+        run: sudo apt install python3-pip pandoc inkscape texlive-latex-extra -y
+      - name: Pip installs
+        run: sudo pip install pylatex
+      - name: Build docs
+        run: python3 docs-generator.py
+      - name: Check if docs are generated
+        run: ls -la
+      - name: Rename to index.html
+        run: mv sigmf-spec.html index.html
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: '.' # Upload entire repository for now, TODO ONLY UPLOAD THE HTML AND PDF IN THE LONG TERM
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,8 @@
+sigmf-spec.toc
+sigmf-spec.tex
+sigmf-spec.pdf
+sigmf-spec.out
+sigmf-spec.log
+sigmf-spec.aux
+svg-inkscape/
+sigmf-spec.html

README.md

@@ -2,9 +2,7 @@
 
 # Signal Metadata Format (SigMF)
 
-Welcome to the SigMF project! The [SigMF specification document](sigmf-spec.md)
-is the `sigmf-spec.md` file in this repository. Below we discuss why and how
-you might use SigMF in your projects.
+Welcome to the SigMF project! The [SigMF specifications can be viewed here](https://sigmf.github.io/SigMF/index.html) or [downloaded as a PDF](https://sigmf.github.io/SigMF/sigmf-spec.pdf). Below we discuss why and how you might use SigMF in your projects.
 
 ## Introduction
 
@@ -83,6 +81,18 @@ The "Core" SigMF standard is intentionally kept limited in scope, additional met
 
 In general, extension publication pull requests should go into the Community Extension repository. Occasionally there is an extension that is so general purpose that it may be warranted to include in the core SigMF Repository `extensions` directory. Opening an issue in this repository for discussion (or noting this in a pull request in the Community Extension repository), or discussing on the SigMF Matrix Chat room is the best way to make that happen.
 
+Software that seeks to perform validation on metadata can open a metafile, parse which extensions are used (if any), then pull the core JSON schema plus the JSON schemas for each extension being used (and optionally, an application-specific schema), then merge the global/captures/annotations objects between all schemas, and disable `additionalProperties` for all three so that typos can be detected.
+
+## PDF Generation of Specifications Document
+
+The main pdf is generated using the following content:
+
+1. `sigmf-schema.json` - global/captures/annotations tables and descriptions, as well as the Abstract
+1. `collection-schema.json` - Collection object documentation
+1. `additional_content.md` - mix of plaintext/markdown/latex for the remaining sections of the document
+
+The script `docs-generator.py` uses Python, PyLaTeX, Pandoc, and Inkscape to create the specifications document in PDF and HTML formats.
+
 ## Frequently Asked Questions
 
 ### Is this a GNU Radio effort?