diff --git a/.github/workflows/respec.yaml b/.github/workflows/respec.yaml index bfa286f72e..bc3a9e88d5 100644 --- a/.github/workflows/respec.yaml +++ b/.github/workflows/respec.yaml @@ -22,6 +22,8 @@ jobs: steps: - uses: actions/checkout@v2 # checkout main branch + with: + fetch-depth: 0 - name: Install dependencies run: npm i diff --git a/scripts/md2html/build.sh b/scripts/md2html/build.sh index 3ddf387c2e..c4c7a51e95 100755 --- a/scripts/md2html/build.sh +++ b/scripts/md2html/build.sh @@ -14,6 +14,7 @@ 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` +latestCopied=none for filename in ../../versions/[3456789].*.md ; do version=$(basename "$filename" .md) node md2html.js --respec --maintainers ../../MAINTAINERS.md ${filename} > ../../deploy/oas/v$version.html @@ -21,7 +22,9 @@ for filename in ../../versions/[3456789].*.md ; do if [[ ${version} != *"rc"* ]];then # version is not a Release Candidate cp -p ../../deploy/oas/v$version.html ../../deploy/oas/latest.html + latestCopied=v$version fi fi done +echo Latest tag is $latest, copied $latestCopied to latest.html diff --git a/scripts/md2html/md2html.js b/scripts/md2html/md2html.js index 26448d1081..23c66adac4 100644 --- a/scripts/md2html/md2html.js +++ b/scripts/md2html/md2html.js @@ -1,8 +1,6 @@ -/* bikeshed claims to support markdown syntax, but not (yet) commonmark. -ReSpec supports markdown formatting, but this shows up on the page before being rendered +/* ReSpec supports markdown formatting, but this shows up on the page before being rendered Hence we render the markdown to HTML ourselves, this gives us -complete control over formatting and syntax highlighting (where -highlight.js does a better job than bikeshed's Pygments) */ +complete control over formatting and syntax highlighting */ 'use strict'; @@ -19,9 +17,6 @@ const hljs = require('highlight.js'); const cheerio = require('cheerio'); let argv = require('yargs') - .boolean('bikeshed') - .alias('b','bikeshed') - .describe('bikeshed','Output in bikeshed format') .boolean('respec') .alias('r','respec') .describe('respec','Output in respec format') @@ -72,6 +67,11 @@ function preface(title,options) { }; let preface = `${md.utils.escapeHtml(title)}`; + + // SEO + preface += ''; + preface += ''; + if (options.respec) { preface += ''; preface += ``; @@ -91,7 +91,7 @@ function preface(title,options) { preface += fs.readFileSync(path.resolve(__dirname,'gist.css'),'utf8').split('\n').join(' '); preface += ''; preface += '
'; - preface += 'The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for REST APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.'; + preface += 'The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.'; preface += '
'; preface += '
'; preface += '

Status of This Document

'; @@ -121,15 +121,24 @@ function doMaintainers() { } function getPublishDate(m) { + let result = new Date(); let h = md.render(m); let $ = cheerio.load(h); - let t = $('tbody').last(); - let c = $(t).children('tr').children('td'); - let v = $(c[0]).text(); - let d = $(c[1]).text(); - argv.subtitle = v; - if (d === 'TBA') return new Date(); - return new Date(d); + $('table').each(function(i,table){ + const h = $(table).find('th'); + const headers = []; + $(h).each(function(i,header){ + headers.push($(header).text()); + }); + if (headers.length >= 2 && headers[0] === 'Version' && headers[1] === 'Date') { + let c = $(table).find('tr').find('td'); + let v = $(c[0]).text(); + let d = $(c[1]).text(); + argv.subtitle = v; + if (d !== 'TBA') result = new Date(d); + } + }); + return result; } if (argv.maintainers) { @@ -178,8 +187,6 @@ for (let l in lines) { let originalIndent = indent; let prevIndent = indents[indents.length-1]; // peek - - /* bikeshed is a bit of a pita when it comes to header nesting */ let delta = indent-prevIndent; if (!argv.respec) { @@ -301,7 +308,7 @@ for (let l in lines) { lines[l] = line; } -s = preface('OpenAPI Specification',argv)+'\n\n'+lines.join('\n'); +s = preface(`OpenAPI Specification v${argv.subtitle} | Introduction, Definitions, & More`,argv)+'\n\n'+lines.join('\n'); let out = md.render(s); out = out.replace(/\[([RGB])\]/g,function(match,group1){ console.warn('Fixing',match,group1);