Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

main: add "Other versions" links to frontmatter of HTML-rendered specs #4401

Merged
merged 1 commit into from
Mar 3, 2025

Conversation

ralfhandl
Copy link
Contributor

This PR resolves a Slack discussion started by @earth2marsh:

While it is pretty easy to reach the latest version of the published spec, it is harder to find the 3.0.x branch, either from the website for from the spec itself. I wonder if we might make it easier to reach other versions we've published?

It includes a list of "Other versions" links to the frontmatter of the HTML-rendered specs, for example

image

Tick one of the following options:

  • schema changes are included in this pull request
  • schema changes are needed for this pull request but not done yet
  • no schema changes are needed for this pull request

@ralfhandl ralfhandl requested review from a team as code owners March 1, 2025 19:02
@ralfhandl ralfhandl added Housekeeping script Pull requests that update Bash or JavaScript code labels Mar 1, 2025
earth2marsh
earth2marsh previously approved these changes Mar 1, 2025
Copy link
Member

@earth2marsh earth2marsh left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Awesome, thanks!

@ralfhandl
Copy link
Contributor Author

@earth2marsh Forgot to adjust the unit tests 🙄

earth2marsh
earth2marsh previously approved these changes Mar 1, 2025
@ralfhandl ralfhandl requested review from a team March 1, 2025 20:39
Copy link
Contributor

@mikekistler mikekistler left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good! 👍

@@ -53,7 +55,7 @@ for specification in $specifications; do

echo === Building $version to $destination

node scripts/md2html/md2html.js --maintainers $maintainers $specification > $tempfile
node scripts/md2html/md2html.js --maintainers $maintainers $specification "$allVersions" > $tempfile
Copy link
Contributor

@duncanbeevers duncanbeevers Mar 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider using a yargs array, rather than overloading the positional argument.

diff --git a/scripts/md2html/build.sh b/scripts/md2html/build.sh
index b40a1a12..c0ef1654 100755
--- a/scripts/md2html/build.sh
+++ b/scripts/md2html/build.sh
@@ -55,7 +55,11 @@ for specification in $specifications; do
 
   echo === Building $version to $destination
 
-  node scripts/md2html/md2html.js --maintainers $maintainers $specification "$allVersions" > $tempfile
+  node scripts/md2html/md2html.js \
+    --maintainers $maintainers \
+    --all-versions $allVersions -- \
+    $specification > $tempfile
+
   npx respec --no-sandbox --use-local --src $tempfile --out $destination
   rm $tempfile
 
diff --git a/scripts/md2html/md2html.js b/scripts/md2html/md2html.js
index c3ff2862..2873b3d4 100644
--- a/scripts/md2html/md2html.js
+++ b/scripts/md2html/md2html.js
@@ -55,6 +55,9 @@ let argv = require('yargs')
     .alias('m','maintainers')
     .describe('maintainers','path to MAINTAINERS.md')
     .demandCommand(1)
+    .array('all-versions')
+    .alias('av', 'all-versions')
+    .describe('all-versions', 'List of all versions of the specification, used for inter-version linking')
     .argv;
 const abstract = 'What is the OpenAPI Specification?';
 let maintainers = [];
@@ -77,7 +80,7 @@ const md = require('markdown-it')({
 });
 
 function preface(title,options) {
-    const otherVersions = options._[1].split("\n").map(v => path.basename(v,'.md')).filter(v => v !== options.subtitle);
+    const otherVersions = options['all-versions'].map(v => path.basename(v,'.md')).filter(v => v !== options.subtitle)
     const respec = {
         specStatus: "base",
         latestVersion: "https://spec.openapis.org/oas/latest.html",

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the suggestion.

If the command-line interface of md2html were to survive, an array of positional parameters could be seen as more elegant, and preferable to a dash-dash option because allVersions is not optional.

In #4234 we plan to move the whole md2html stuff to a separate repository and reshape it into a GitHub action, which will remove the current yargs solution along with all bash parts and replace it with a JS function md2html(spec,editors,formerEditors,allVersions) or similar. So I don't want to invest into the current command-line interface.

@ralfhandl ralfhandl merged commit 428007d into OAI:main Mar 3, 2025
2 checks passed
@ralfhandl ralfhandl deleted the main-respec-other-versions branch March 3, 2025 07:48
@ralfhandl
Copy link
Contributor Author

Merged as the current state is what @earth2marsh previously approved plus the repaired unit tests.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Housekeeping script Pull requests that update Bash or JavaScript code
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants