From 079cbb41ce7d0e0aca884c8d7d9db1f9c7a3c465 Mon Sep 17 00:00:00 2001 From: Marc Lichtman Date: Wed, 28 Aug 2024 23:47:30 -0400 Subject: [PATCH] num_channels wording and updated github action to be able to view pdf/html as an artifact (#319) * num_channels wording * Update additional_content.md * Update generate_docs_pr.yml * Update generate_docs_pr.yml * Update README.md * Update additional_content.md * Update additional_content.md * Update .github/workflows/generate_docs_pr.yml Co-authored-by: Teque5 * Update README.md Co-authored-by: Teque5 * Update generate_docs.yml * Update generate_docs_pr.yml * Update generate_docs.yml * Update generate_docs_pr.yml * Update generate_docs.yml * Update generate_docs_pr.yml --------- Co-authored-by: Teque5 --- .github/workflows/generate_docs.yml | 4 +++- .github/workflows/generate_docs_pr.yml | 9 ++++++++- README.md | 2 ++ additional_content.md | 13 +++---------- sigmf-schema.json | 4 ++-- 5 files changed, 18 insertions(+), 14 deletions(-) diff --git a/.github/workflows/generate_docs.yml b/.github/workflows/generate_docs.yml index 2f9fa6e..53eb770 100644 --- a/.github/workflows/generate_docs.yml +++ b/.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 diff --git a/.github/workflows/generate_docs_pr.yml b/.github/workflows/generate_docs_pr.yml index 51432c3..3fb8cda 100644 --- a/.github/workflows/generate_docs_pr.yml +++ b/.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: '.' diff --git a/README.md b/README.md index 246e98d..2c5ebfe 100644 --- a/README.md +++ b/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? diff --git a/additional_content.md b/additional_content.md index 4029c77..be35614 100644 --- a/additional_content.md +++ b/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} diff --git a/sigmf-schema.json b/sigmf-schema.json index 0b7903f..a0f755e 100644 --- a/sigmf-schema.json +++ b/sigmf-schema.json @@ -65,7 +65,7 @@ "type": "string" }, "core:num_channels": { - "description": "Total number of interleaved channels in the Dataset file; if omitted this is implied to be 1. For multiple channels of IQ data, it is RECOMMENDED to use SigMF Collections instead of num_channels for widest application support.", + "description": "Number of interleaved channels in the Dataset file, if omitted this is implied to be 1, for multiple channels of IQ data, it is RECOMMENDED to use SigMF Collections instead of num_channels for widest application support.", "default": 1, "minimum": 1, "maximum": 1000, @@ -124,7 +124,7 @@ } }, "core:extensions": { - "description": "The `core:extensions` field in the Global Object is an array of extension objects that describe SigMF extensions. Extension Objects MUST contain the three key/value pairs defined below, and MUST NOT contain any other fields. \\rowcolors{1}{}{lightblue}\\begin{center}\\begin{tabular}{lllp{3.8in}} \\toprule \\textbf{Name} & \\textbf{Required} & \\textbf{Type} & \\textbf{Description} \\\\ \\midrule name & true & string & The name of the SigMF extension namespace. \\\\ version & true & string & The version of the extension namespace specification used. \\\\ optional & true & boolean & If this field is `false`, then the application MUST support this extension in order to parse the Recording; if the application does not support this extension, it SHOULD report an error. \\\\ \\bottomrule \\end{tabular} \\end{center} In the example below, `extension-01` is optional, so the application may ignore it if it does not support `extension-01`. But `extension-02` is not optional, so the application must support `extension-02` in order to parse the Recording. \\begin{verbatim}\"global\": {\n ...\n \"core:extensions\" : [\n {\n \"name\": \"extension-01\",\n \"version\": \"0.0.5\",\n \"optional\": true\n },\n {\n \"name\": \"extension-02\",\n \"version\": \"1.2.3\",\n \"optional\": false\n }\n ]\n ...\n }\\end{verbatim}", + "description": "The `core:extensions` field in the Global Object is an array of extension objects that describe SigMF extensions. Extension Objects MUST contain the three key/value pairs defined below, and MUST NOT contain any other fields. \\rowcolors{1}{}{lightblue}\\begin{center}\\begin{tabular}{lllp{3.8in}} \\toprule \\textbf{Name} & \\textbf{Required} & \\textbf{Type} & \\textbf{Description} \\\\ \\midrule name & true & string & The name of the SigMF extension namespace. \\\\ version & true & string & The version of the extension namespace specification used. \\\\ optional & true & boolean & If this field is `false`, then the application MUST support this extension in order to parse the Recording; if the application does not support this extension, it SHOULD report an error. \\\\ \\bottomrule \\end{tabular} \\end{center} \\\\ In the example below, `extension-01` is optional, so the application may ignore it if it does not support `extension-01`. But `extension-02` is not optional, so the application must support `extension-02` in order to parse the Recording. \\begin{verbatim}\"global\": {\n ...\n \"core:extensions\" : [\n {\n \"name\": \"extension-01\",\n \"version\": \"0.0.5\",\n \"optional\": true\n },\n {\n \"name\": \"extension-02\",\n \"version\": \"1.2.3\",\n \"optional\": false\n }\n ]\n ...\n }\\end{verbatim}", "type": "array", "default": [], "additionalItems": false,