From 3d83a95bf986aebaaa58a7c8ffd6dfe89f78cff0 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Mon, 16 Dec 2024 11:07:09 +0100 Subject: [PATCH 1/5] Build HTML from src/oas.md --- .gitignore | 1 + package.json | 1 + scripts/md2html/build-src.sh | 26 ++++++++++++++++++++++++++ 3 files changed, 28 insertions(+) create mode 100755 scripts/md2html/build-src.sh diff --git a/.gitignore b/.gitignore index fadcdf5db7..ed69dc8553 100644 --- a/.gitignore +++ b/.gitignore @@ -7,5 +7,6 @@ atlassian-ide-plugin.xml node_modules/ deploy/ coverage/ +src-preview/ history Gemfile.lock diff --git a/package.json b/package.json index 7ca32dab47..3a44f74d95 100644 --- a/package.json +++ b/package.json @@ -14,6 +14,7 @@ "license": "Apache-2.0", "scripts": { "build": "bash ./scripts/md2html/build.sh", + "build-src": "bash ./scripts/md2html/build-src.sh", "test": "c8 --100 vitest --watch=false && bash scripts/schema-test-coverage.sh", "validate-markdown": "npx mdv src/oas.md && npx markdownlint-cli src/oas.md" }, diff --git a/scripts/md2html/build-src.sh b/scripts/md2html/build-src.sh new file mode 100755 index 0000000000..0a2291d893 --- /dev/null +++ b/scripts/md2html/build-src.sh @@ -0,0 +1,26 @@ +#!/usr/bin/env bash + +# Author: @ralfhandl + +# run this script from the root of the repo + +mkdir -p deploy/oas +mkdir -p deploy/js +mkdir -p src-preview + +cd scripts/md2html + +cp -p ../../node_modules/respec/builds/respec-w3c.* ../../deploy/js/ + +filename=src/oas.md +tempfile=../../deploy/oas/oas.html +echo "=== ${filename} ===" + +node md2html.js --maintainers ../../EDITORS.md ../../${filename} > $tempfile +npx respec --use-local --src $tempfile --out ../../src-preview/oas.html +rm $tempfile + +echo Built src-preview/oas.html +echo + +rm ../../deploy/js/respec-w3c.* From a3425f2ffd67c3fdf289d85384110a63577a2fee Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 19 Dec 2024 20:55:56 +0100 Subject: [PATCH 2/5] builld into deploy-preview --- .gitignore | 2 +- scripts/md2html/build-src.sh | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.gitignore b/.gitignore index ed69dc8553..f3ff4ab93f 100644 --- a/.gitignore +++ b/.gitignore @@ -6,7 +6,7 @@ target atlassian-ide-plugin.xml node_modules/ deploy/ +deploy-preview/ coverage/ -src-preview/ history Gemfile.lock diff --git a/scripts/md2html/build-src.sh b/scripts/md2html/build-src.sh index 0a2291d893..fd0cb8d3de 100755 --- a/scripts/md2html/build-src.sh +++ b/scripts/md2html/build-src.sh @@ -6,21 +6,21 @@ mkdir -p deploy/oas mkdir -p deploy/js -mkdir -p src-preview +mkdir -p deploy-preview -cd scripts/md2html +cp -p node_modules/respec/builds/respec-w3c.* deploy/js/ -cp -p ../../node_modules/respec/builds/respec-w3c.* ../../deploy/js/ +cd scripts/md2html filename=src/oas.md tempfile=../../deploy/oas/oas.html echo "=== ${filename} ===" node md2html.js --maintainers ../../EDITORS.md ../../${filename} > $tempfile -npx respec --use-local --src $tempfile --out ../../src-preview/oas.html +npx respec --use-local --src $tempfile --out ../../deploy-preview/oas.html rm $tempfile -echo Built src-preview/oas.html +echo Built deploy-preview/oas.html echo rm ../../deploy/js/respec-w3c.* From 0b187b69459a3d25f91011574447202a4cd8758c Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Mon, 23 Dec 2024 12:00:13 +0100 Subject: [PATCH 3/5] Temp files in deploy-preview --- scripts/md2html/build-src.sh | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/scripts/md2html/build-src.sh b/scripts/md2html/build-src.sh index fd0cb8d3de..2201d45f92 100755 --- a/scripts/md2html/build-src.sh +++ b/scripts/md2html/build-src.sh @@ -4,16 +4,15 @@ # run this script from the root of the repo -mkdir -p deploy/oas -mkdir -p deploy/js mkdir -p deploy-preview +mkdir -p deploy-preview/js -cp -p node_modules/respec/builds/respec-w3c.* deploy/js/ +cp -p node_modules/respec/builds/respec-w3c.* deploy-preview/js/ cd scripts/md2html filename=src/oas.md -tempfile=../../deploy/oas/oas.html +tempfile=../../deploy-preview/oas-temp.html echo "=== ${filename} ===" node md2html.js --maintainers ../../EDITORS.md ../../${filename} > $tempfile @@ -23,4 +22,4 @@ rm $tempfile echo Built deploy-preview/oas.html echo -rm ../../deploy/js/respec-w3c.* +rm ../../deploy-preview/js/respec-w3c.* From b9c7b9112412b85954a11a2b0e13cd5d34dc0d6f Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Mon, 23 Dec 2024 18:38:15 +0100 Subject: [PATCH 4/5] Tempfile in folder next to js folder --- scripts/md2html/build-src.sh | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/scripts/md2html/build-src.sh b/scripts/md2html/build-src.sh index 2201d45f92..ff972b7f84 100755 --- a/scripts/md2html/build-src.sh +++ b/scripts/md2html/build-src.sh @@ -4,7 +4,7 @@ # run this script from the root of the repo -mkdir -p deploy-preview +mkdir -p deploy-preview/temp mkdir -p deploy-preview/js cp -p node_modules/respec/builds/respec-w3c.* deploy-preview/js/ @@ -12,7 +12,7 @@ cp -p node_modules/respec/builds/respec-w3c.* deploy-preview/js/ cd scripts/md2html filename=src/oas.md -tempfile=../../deploy-preview/oas-temp.html +tempfile=../../deploy-preview/temp/oas.html echo "=== ${filename} ===" node md2html.js --maintainers ../../EDITORS.md ../../${filename} > $tempfile @@ -22,4 +22,5 @@ rm $tempfile echo Built deploy-preview/oas.html echo -rm ../../deploy-preview/js/respec-w3c.* +rm -r ../../deploy-preview/js +rmdir ../../deploy-preview/temp From 8a2bb1732ca9c1985007a78341ae68bb8a8923cc Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 15 Jan 2025 12:00:04 +0100 Subject: [PATCH 5/5] Preview and lint spec changes --- CONTRIBUTING.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 246fa567bd..f6c33f06b1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -163,6 +163,21 @@ This might apply to, for example, Markdown files, automation, and scripts. For all pull requests, if they should not be merged yet for any reason (they depend on something else, you would like feedback from a specific reviewer), mark them as draft and they will not be merged while in that state. Draft pull requests can still be reviewed while in draft state. +### Preview specification HTML locally + +The markdown source files are converted to HTML before publishing. +To do this locally, please + +1. Install [Node.js](https://nodejs.org/) +2. Check out this repo, go to the repo root, and switch to a development branch +3. Execute `npm install` (once, repeat after merging upstream changes) +4. Execute `npm run build-src` after changing `src/oas.md` +5. Open output file `deploy-preview/oas.html` with a browser + +Before creating a pull request or marking a draft pull request as ready for review, please + +6. Execute `npm run validate-markdown` and fix any reported problems in `src/oas.md` + ## Reviewers > [!NOTE]