Skip to content

Commit cc45c37

Browse files
MikeRalphsonMikeRalphson
authored
Add script and GitHub action to automatically generate ReSpec versions of the spec (#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 #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]>
1 parent a295d9a commit cc45c37

File tree

11 files changed

+586
-1
lines changed

11 files changed

+586
-1
lines changed

‎.github/workflows/respec.yaml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: respec
2+
3+
# author: @MikeRalphson
4+
# issue: https://github.com/OAI/OpenAPI-Specification/issues/1564
5+
6+
#
7+
# This workflow updates the respec 'pretty' rendered versions of the spec
8+
# on the gh-pages branch when the corresponding markdown files change.
9+
#
10+
11+
# run this on push to main
12+
on:
13+
push:
14+
branches:
15+
- main
16+
workflow_dispatch: {}
17+
18+
jobs:
19+
respec:
20+
21+
runs-on: ubuntu-latest
22+
23+
steps:
24+
- uses: actions/checkout@v2 # checkout main branch
25+
26+
- name: Install dependencies
27+
run: npm i
28+
29+
- uses: actions/checkout@v2 # checkout gh-pages branch
30+
with:
31+
ref: gh-pages
32+
path: deploy
33+
34+
- name: run main script
35+
run: scripts/md2html/build.sh
36+
37+
- name: Create Pull Request
38+
uses: peter-evans/create-pull-request@v3
39+
with:
40+
token: ${{ secrets.GITHUB_TOKEN }}
41+
branch: update-respec-version
42+
base: gh-pages
43+
delete-branch: true
44+
path: deploy
45+
labels: Housekeeping
46+
reviewers: webron,darrelmiller
47+
title: Update ReSpec versions
48+
commit-message: Update ReSpec versions
49+
signoff: true
50+
body: |
51+
This pull request is automatically triggered by GitHub action `respec`.
52+
53+
The versions/v*.md files have changed, so the HTML files are automatically being regenerated.
54+
55+

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,6 @@ target
66
atlassian-ide-plugin.xml
77
node_modules/
88
package-lock.json
9+
deploy/
10+
history
911
Gemfile.lock

‎package.json‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,12 @@
1717
"README.md",
1818
"schemas/*"
1919
],
20-
"dependencies": {},
20+
"dependencies": {
21+
"cheerio": "^1.0.0-rc.5",
22+
"highlight.js": "^10.6.0",
23+
"markdown-it": "^12.0.4",
24+
"yargs": "^12.0.5"
25+
},
2126
"devDependencies": {
2227
"@hyperjump/json-schema": "^0.17.0",
2328
"chai": "^4.3.1",

‎scripts/md2html/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
*.err
2+
input.bs

‎scripts/md2html/analytics/google.html‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
<!-- Global site tag (gtag.js) - Google Analytics -->
2+
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-831873-42"></script>
3+
<script>
4+
window.dataLayer = window.dataLayer || [];
5+
function gtag(){dataLayer.push(arguments);}
6+
gtag('js', new Date());
7+
gtag('config', 'UA-831873-42');
8+
</script>

‎scripts/md2html/build.sh‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
#!/bin/sh
2+
3+
# run this script from the root of the repo
4+
5+
mkdir -p deploy/oas
6+
mkdir -p deploy/js
7+
8+
cd scripts/md2html
9+
mkdir -p history
10+
git show c740e950d:MAINTAINERS.md > history/MAINTAINERS_v2.0.md
11+
cp -p js/* ../../deploy/js 2> /dev/null
12+
cp -p markdown/* ../../deploy/ 2> /dev/null
13+
14+
node md2html.js --respec --maintainers ./history/MAINTAINERS_v2.0.md ../../versions/2.0.md > ../../deploy/oas/v2.0.html
15+
16+
latest=`git describe --abbrev=0 --tags`
17+
for filename in ../../versions/[3456789].*.md ; do
18+
version=$(basename "$filename" .md)
19+
node md2html.js --respec --maintainers ../../MAINTAINERS.md ${filename} > ../../deploy/oas/v$version.html
20+
if [ $version = $latest ]; then
21+
if [[ ${version} != *"rc"* ]];then
22+
# version is not a Release Candidate
23+
cp -p ../../deploy/oas/v$version.html ../../deploy/oas/latest.html
24+
fi
25+
fi
26+
done
27+

‎scripts/md2html/gist.css‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
/**
2+
* GitHub Gist Theme
3+
* Author : Louis Barranqueiro - https://github.com/LouisBarranqueiro
4+
*/
5+
6+
.hljs {
7+
display: block;
8+
background: white;
9+
padding: 0.5em;
10+
color: #333333;
11+
overflow-x: auto;
12+
}
13+
14+
.hljs-comment,
15+
.hljs-meta {
16+
color: #969896;
17+
}
18+
19+
.hljs-string,
20+
.hljs-variable,
21+
.hljs-template-variable,
22+
.hljs-strong,
23+
.hljs-emphasis,
24+
.hljs-quote {
25+
color: #df5000;
26+
}
27+
28+
.hljs-keyword,
29+
.hljs-selector-tag,
30+
.hljs-type {
31+
color: #a71d5d;
32+
}
33+
34+
.hljs-literal,
35+
.hljs-symbol,
36+
.hljs-bullet,
37+
.hljs-attribute {
38+
color: #0086b3;
39+
}
40+
41+
.hljs-section,
42+
.hljs-name {
43+
color: #63a35c;
44+
}
45+
46+
.hljs-tag {
47+
color: #333333;
48+
}
49+
50+
.hljs-title,
51+
.hljs-attr,
52+
.hljs-selector-id,
53+
.hljs-selector-class,
54+
.hljs-selector-attr,
55+
.hljs-selector-pseudo {
56+
color: #795da3;
57+
}
58+
59+
.hljs-addition {
60+
color: #55a532;
61+
background-color: #eaffea;
62+
}
63+
64+
.hljs-deletion {
65+
color: #bd2c00;
66+
background-color: #ffecec;
67+
}
68+
69+
.hljs-link {
70+
text-decoration: underline;
71+
}

0 commit comments

Comments
 (0)