ReSpec: align with OAI/OpenAPI-Specification

.github/workflows/respec.yaml

@@ -11,7 +11,7 @@ name: respec
 on:
   push:
     paths:
-      - "versions/**"
+      - "versions/[0-9].[0-9].[0-9].md"
     branches:
       - main
   workflow_dispatch: {}

.gitignore

@@ -6,6 +6,7 @@ target
 atlassian-ide-plugin.xml
 node_modules/
 deploy/
+deploy-preview/
 coverage/
 history
 Gemfile.lock

CONTRIBUTING.md

@@ -43,7 +43,7 @@ The `main` branch holds
 
 Other branches are usually short-lived, for example and for maintaining utility scripts.
 
-## Build the HTML version to publish
+## Build the HTML versions locally
 
 We use ReSpec to render the markdown specification as HTML for publishing and easier reading.
 These instructions explain how you can build the HTML locally.
@@ -56,13 +56,17 @@ Install dependencies:
 npm install
 ```
 
-Produce stand-alone HTML files in the local `deploy/overlay` folder:
+Produce stand-alone HTML files for all final specifications in the local `deploy/overlay` folder:
 
 ```sh
 npm run build
 ```
 
-Note that Linux users may need to add `--no-sandbox` to run `npx respec` as found in the `scripts/md2html/build.sh` file.
+Produce stand-alone HTML files for all work-in-progress specifications in the local `deploy-preview` folder:
+
+```sh
+npm run build-dev
+```
 
 ## Style guide for Overlay Specification
 

EDITORS.md

@@ -2,10 +2,14 @@
 
 ## Active
 
+* Lorna Mitchell [@lornajane](https://github.com/lornajane)
+* Mike Kistler [@mikekistler](https://github.com/mikekistler)
+* Vincent Biret [@baywet](https://github.com/baywet)
+
+## Emeritus
+
 * Darrel Miller [@darrelmiller](https://github.com/darrelmiller)
 * Greg Dennis [@gregsdennis](https://github.com/gregsdennis)
 * Kevin Swiber [@kevinswiber](https://github.com/kevinswiber)
-* Lorna Mitchell [@lornajane](https://github.com/lornajane)
-* Mike Kistler [@mikekistler](https://github.com/mikekistler)
 * Mike Ralphson [@MikeRalphson](https://github.com/MikeRalphson)
 * Ron Ratovsky [@webron](https://github.com/webron)

package.json

@@ -40,6 +40,7 @@
   ],
   "scripts": {
     "build": "bash ./scripts/md2html/build.sh",
+    "build-dev": "bash ./scripts/md2html/build.sh dev",
     "format-markdown": "bash ./scripts/format-markdown.sh ./versions/*.md",
     "test": "c8 --100 vitest run --coverage"
   }

scripts/md2html/build.sh

@@ -2,47 +2,83 @@
 
 # Author: @ralfhandl (inspired by the work of @MikeRalphson)
 
-# run this script from the root of the repo. It is designed to be run by a GitHub workflow.
+# run this script from the root of the repo
+# It is designed to be run by a GitHub workflow
+
+# Usage: build.sh [version | "latest" | "dev"]
+# When run with no arguments, it builds artifacts for all published specification versions.
+# It may also be run with a specific version argument, such as "1.0.0" or "latest"
+# Finally, it may be run with "dev" to build "versions/*-dev.md"
+#
 # It contains bashisms
 
-mkdir -p deploy/overlay
-mkdir -p deploy/js
+if [ "$1" = "dev" ]; then
+  deploydir="deploy-preview"
+else
+  deploydir="deploy/overlay"
+fi
+
+mkdir -p $deploydir/js
+mkdir -p $deploydir/temp
+cp -p node_modules/respec/builds/respec-w3c.* $deploydir/js/
 
-cd scripts/md2html
-mkdir -p history
-cp ../../EDITORS.md history/EDITORS_v1.0.0.md
+latest=$(git describe --abbrev=0 --tags)
 
-# temporarily copy installed version of respec into build directory
-cp -p ../../node_modules/respec/builds/respec-w3c.* ../../deploy/js/
+if [ -z "$1" ]; then
+  specifications=$(ls -1 versions/[1-9].[0-9].[0-9].md | sort -r)
+elif [ "$1" = "latest" ]; then
+  specifications=$(ls -1 versions/$latest.md)
+elif [ "$1" = "dev" ]; then
+  specifications=$(ls -1 versions/[1-9].[0-9].[0-9]-dev.md | sort -r)
+else
+  specifications=$(ls -1 versions/$1.md)
+fi
 
-# latest=`git describe --abbrev=0 --tags` -- introduce after release tags created
-latest=1.0.0
-latestCopied=none
+latestCopied="none"
 lastMinor="-"
-for filename in $(ls -1 ../../versions/[1-9].[0-9].[0-9].md | sort -r) ; do
-  version=$(basename "$filename" .md)
+
+for specification in $specifications; do
+  version=$(basename "$specification" .md)
+
+  destination="$deploydir/v$version.html"
+  if [ "$1" = "dev" ]; then
+    maintainers="EDITORS.md"
+  else
+    maintainers="$(dirname $specification)/$version-editors.md"
+  fi
+
   minorVersion=${version:0:3}
-  tempfile=../../deploy/overlay/v$version-tmp.html
-  echo -e "\n=== v$version ==="
+  tempfile="$deploydir/temp/$version.html"
+  tempfile2="$deploydir/temp/$version-2.html"
+
+  echo === Building $version to $destination
 
-  node md2html.js --maintainers ./history/EDITORS_v$version.md ${filename} > $tempfile
-  npx respec --use-local --src $tempfile --out ../../deploy/overlay/v$version.html
-  rm $tempfile
+  node scripts/md2html/md2html.js --maintainers $maintainers $specification "$allVersions" > $tempfile
+  npx respec --no-sandbox --use-local --src $tempfile --out $tempfile2
+  # remove unwanted Google Tag Manager and Google Analytics scripts
+  sed -e 's/<script type="text\/javascript" async="" src="https:\/\/www.google-analytics.com\/analytics.js"><\/script>//' \
+      -e 's/<script type="text\/javascript" async="" src="https:\/\/www.googletagmanager.com\/gtag\/js?id=G-[^"]*"><\/script>//' \
+      $tempfile2 > $destination
+
+  echo === Built $destination
 
   if [ $version = $latest ]; then
-    if [[ ${version} != *"rc"* ]];then
+    if [[ ${version} != *"rc"* ]]; then
       # version is not a Release Candidate
-      ( cd ../../deploy/overlay && ln -sf v$version.html latest.html )
-      latestCopied=v$version
+      ln -sf $(basename $destination) $deploydir/latest.html
+      latestCopied="v$version"
     fi
   fi
 
-  if [ ${minorVersion} != ${lastMinor} ]; then
-    ( cd ../../deploy/overlay && ln -sf v$version.html v$minorVersion.html )
+  if [ ${minorVersion} != ${lastMinor} ] && [ -z "$1" ]; then
+    ln -sf $(basename $destination) $deploydir/v$minorVersion.html
     lastMinor=$minorVersion
   fi
 done
-echo Latest tag is $latest, copied $latestCopied to latest.html
 
-# clean up build directory
-rm ../../deploy/js/respec-w3c.*
+if [ "$latestCopied" != "none" ]; then
+  echo Latest tag is $latest, copied $latestCopied to latest.html
+fi
+
+rm -r $deploydir/js
+rm -r $deploydir/temp

scripts/md2html/md2html.js

@@ -36,7 +36,8 @@ const md = require('markdown-it')({
       '</code></pre>';
     }
 
-    return '<pre class="highlight '+lang+'" tabindex="0"><code>' + md.utils.escapeHtml(str) + '</code></pre>';
+    if (lang) console.warn('highlight.js does not support language',lang);
+    return '<pre class="nohighlight" tabindex="0"><code>' + md.utils.escapeHtml(str) + '</code></pre>';
   }
 });
 
@@ -87,16 +88,16 @@ function preface(title,options) {
         // }
     };
 
-    let preface = `<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><title>${md.utils.escapeHtml(title)}</title>`;
+    let preface = '<!DOCTYPE html><html lang="en"><head>\n'
+    preface += fs.readFileSync(path.resolve(__dirname,'./analytics/google.html'),'utf8');
+
+    // SEO
+    preface += `<meta charset="UTF-8">\n<title>${md.utils.escapeHtml(title)}</title>`;
 
     // ReSpec
     preface += '<script src="../js/respec-w3c.js" class="remove"></script>';
-    preface += `<script class="remove">var respecConfig = ${JSON.stringify(respec)};</script>`;
-    try {
-        preface += fs.readFileSync('./analytics/google.html','utf8');
-    }
-    catch (ex) {}
-    preface += '</head><body>';
+    preface += `<script class="remove">var respecConfig = ${JSON.stringify(respec)};</script>\n`;
+    preface += '</head>\n<body>';
     preface += '<style>';
     preface += '#respec-ui { visibility: hidden; }';
     preface += '#title { color: #578000; } #subtitle { color: #578000; }';
@@ -159,7 +160,7 @@ function getPublishDate(m) {
             let v = $(c[0]).text();
             let d = $(c[1]).text();
             argv.subtitle = v;
-            if (d !== 'TBA') result = new Date(d);
+            if (d !== 'TBD') result = new Date(d);
         }
     });
     return result;

versions/1.0.0-editors.md

@@ -0,0 +1,11 @@
+# Overlay Specification Editors
+
+## Active
+
+* Darrel Miller [@darrelmiller](https://github.com/darrelmiller)
+* Greg Dennis [@gregsdennis](https://github.com/gregsdennis)
+* Kevin Swiber [@kevinswiber](https://github.com/kevinswiber)
+* Lorna Mitchell [@lornajane](https://github.com/lornajane)
+* Mike Kistler [@mikekistler](https://github.com/mikekistler)
+* Mike Ralphson [@MikeRalphson](https://github.com/MikeRalphson)
+* Ron Ratovsky [@webron](https://github.com/webron)