Add script and GitHub action to automatically generate ReSpec version…

…s of the spec (OAI#2574)

* workflows: update used actions

* .

* bikeshed rendering (WIP)

* bikeshed; split into v2, v3 directories

* bikeshed; fixes to TOC,code blocks and indent levels

* bikeshed; work from unmodified .md files

* bikeshed; .gitignore

* bikeshed; separate header for v3.0.1 for now

* respec; as an alternative to bikeshed

* Rename bikeshed to md2html

* md2html; current setup

* md2html; wip

* md2html; fix 1 toc bug

* md2html; fix another toc bug

* md2html; fix 1 respec toc bug

* md2html; fix another bikeshed toc bug

* respec; former editor support - needs ReSpec 20.x

* Latest respec tweaks

* pre block css background, RFC ref fixes

* Github gist syntax highlighting css

* md2html: move to scripts dir

* md2html: resolve relative links for examples

* md2html: use respec js from spec.openapis.org site

* md2html: find gist.css regardless of run dir

* md2html: don't mix https and http content (toc)

* md2html; include google analytics

* md2html; build putative versions 4,5 etc

* md2html; tidying up

* md2html; specify lang="en" in html

* build: update deps

* fix: style examples bugs, refs OAI#2488

* fix: update highlightjs call in md2html

* feat: add github action

Signed-off-by: Mike Ralphson <[email protected]>

* build: create a `latest.html` ReSpec version

Signed-off-by: Mike Ralphson <[email protected]>

.github/workflows/respec.yaml

@@ -0,0 +1,55 @@
+name: respec
+
+# author: @MikeRalphson
+# issue: https://github.com/OAI/OpenAPI-Specification/issues/1564
+
+#
+# This workflow updates the respec 'pretty' rendered versions of the spec 
+# on the gh-pages branch when the corresponding markdown files change.
+#
+
+# run this on push to main
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch: {}
+
+jobs:
+  respec:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2 # checkout main branch
+
+    - name: Install dependencies
+      run: npm i
+
+    - uses: actions/checkout@v2 # checkout gh-pages branch
+      with:
+        ref: gh-pages
+        path: deploy
+
+    - name: run main script
+      run: scripts/md2html/build.sh
+
+    - name: Create Pull Request
+      uses: peter-evans/create-pull-request@v3
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+        branch: update-respec-version
+        base: gh-pages
+        delete-branch: true
+        path: deploy
+        labels: Housekeeping
+        reviewers: webron,darrelmiller
+        title: Update ReSpec versions
+        commit-message: Update ReSpec versions
+        signoff: true
+        body: |
+          This pull request is automatically triggered by GitHub action `respec`.
+
+          The versions/v*.md files have changed, so the HTML files are automatically being regenerated.
+
+

.gitignore

@@ -6,4 +6,6 @@ target
 atlassian-ide-plugin.xml
 node_modules/
 package-lock.json
+deploy/
+history
 Gemfile.lock

package.json

@@ -17,7 +17,12 @@
     "README.md",
     "schemas/*"
   ],
-  "dependencies": {},
+  "dependencies": {
+    "cheerio": "^1.0.0-rc.5",
+    "highlight.js": "^10.6.0",
+    "markdown-it": "^12.0.4",
+    "yargs": "^12.0.5"
+  },
   "devDependencies": {
     "@hyperjump/json-schema": "^0.17.0",
     "chai": "^4.3.1",

scripts/md2html/.gitignore

@@ -0,0 +1,2 @@
+*.err
+input.bs

scripts/md2html/analytics/google.html

@@ -0,0 +1,8 @@
+<!-- Global site tag (gtag.js) - Google Analytics -->
+<script async src="https://www.googletagmanager.com/gtag/js?id=UA-831873-42"></script>
+<script>
+ window.dataLayer = window.dataLayer || [];
+ function gtag(){dataLayer.push(arguments);}
+ gtag('js', new Date());
+ gtag('config', 'UA-831873-42');
+</script>

scripts/md2html/build.sh

@@ -0,0 +1,27 @@
+#!/bin/sh
+
+# run this script from the root of the repo
+
+mkdir -p deploy/oas
+mkdir -p deploy/js
+
+cd scripts/md2html
+mkdir -p history
+git show c740e950d:MAINTAINERS.md > history/MAINTAINERS_v2.0.md
+cp -p js/* ../../deploy/js 2> /dev/null
+cp -p markdown/* ../../deploy/ 2> /dev/null
+
+node md2html.js --respec --maintainers ./history/MAINTAINERS_v2.0.md ../../versions/2.0.md > ../../deploy/oas/v2.0.html
+
+latest=`git describe --abbrev=0 --tags`
+for filename in ../../versions/[3456789].*.md ; do
+  version=$(basename "$filename" .md)
+  node md2html.js --respec --maintainers ../../MAINTAINERS.md ${filename} > ../../deploy/oas/v$version.html
+  if [ $version = $latest ]; then
+    if [[ ${version} != *"rc"* ]];then
+      # version is not a Release Candidate
+      cp -p ../../deploy/oas/v$version.html ../../deploy/oas/latest.html
+    fi
+  fi
+done
+

scripts/md2html/gist.css

@@ -0,0 +1,71 @@
+/**
+ * GitHub Gist Theme
+ * Author : Louis Barranqueiro - https://github.com/LouisBarranqueiro
+ */
+
+.hljs {
+  display: block;
+  background: white;
+  padding: 0.5em;
+  color: #333333;
+  overflow-x: auto;
+}
+
+.hljs-comment,
+.hljs-meta {
+  color: #969896;
+}
+
+.hljs-string,
+.hljs-variable,
+.hljs-template-variable,
+.hljs-strong,
+.hljs-emphasis,
+.hljs-quote {
+  color: #df5000;
+}
+
+.hljs-keyword,
+.hljs-selector-tag,
+.hljs-type {
+  color: #a71d5d;
+}
+
+.hljs-literal,
+.hljs-symbol,
+.hljs-bullet,
+.hljs-attribute {
+  color: #0086b3;
+}
+
+.hljs-section,
+.hljs-name {
+  color: #63a35c;
+}
+
+.hljs-tag {
+  color: #333333;
+}
+
+.hljs-title,
+.hljs-attr,
+.hljs-selector-id,
+.hljs-selector-class,
+.hljs-selector-attr,
+.hljs-selector-pseudo {
+  color: #795da3;
+}
+
+.hljs-addition {
+  color: #55a532;
+  background-color: #eaffea;
+}
+
+.hljs-deletion {
+  color: #bd2c00;
+  background-color: #ffecec;
+}
+
+.hljs-link {
+  text-decoration: underline;
+}