Unify build scripts; build.sh & build-src.sh

[duncanbeevers]

🗣️ Discussion

This PR depends on #4342 and #4344, per this comment.
This PR supersedes #4340.

In the dev branch there are two implementations of the build process.

• a simple build-src implementation, which builds from src/oas.md into /deploy-preview
• a CI-focused implementation, which builds from versions/*.md into /deploy/oas

Each implementation conducts its clean-up slightly differently, and the CI-focused implementation does some housework around generating MAINTAINERS files to accompany older specification versions.

This PR combines the two kinds of functionality into a single script.

Notable non-changes

• build.sh with no arguments, and hence CI, continues to operate as before, generating the full suite of documentation and symlinks
• npm run build and npm run build-src continue to operate as before, generating the suite, and the src/oas.md documentation, respectively.

Notable changes

🥬 indicates New capabilities
⚡ indicates Departures from old behavior or assumptions
🚧 indicates Reverted changes

• 🥬 Running npm run build 3.1.1 with a single version argument builds the documentation for the specified version
• 🥬 Running npm run build latest builds the documentation for the last-tagged version
• 🥬 Running npm run build src builds the documentation for the src/oas.md specification
• ⚡ Scripts no longer change the working directory; all cd, pushd, and popd calls are removed
• ⚡ /scripts/md2html/md2html.js loads Google Analytics scripts, regardless of the $cwd; tests are updated
• ⚡ /deploy/js is removed during cleanup
• 🚧 /history directory containing historical MAINTAINERS.md versions is created at repository root
• 🚧 /history is removed during cleanup
• ⚡ Cherry-picked materialized history

I validated that the tests pass (and were updated to include the Google Analytics snippet).
I also validated that all the produced artifacts in this PR are identical to their counterparts from the dev branch, including:

• npm run build-src creates identical /deploy-preview/oas.html
• npm run build creates identical /deploy/oas/, including file names, content, and symlink references

Checklist

• 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]

@duncanbeevers Great work, and definitely going into the right direction!

Unfortunately the dev branch is behind the main branch regarding the build process, so it may be easier to retarget to or restart from main, where for example the whole "history" magic has been removed in favor of static *-editors.md files accompanying each specification version file.

Sorry for the inconvenience!

[ralfhandl]

As the src folder and its related scripts intentionally don't exist on main, this PR needs to be split up:

• changes to build.sh, md2html.js, and the test fixtures in a PR targeting main
• once that is merged and synced to dev, a second PR targeting dev changing package.json and removing build-src.sh, which can then be merged and synced to the v3.*-dev branches.

[duncanbeevers]

@ralfhandl I've removed the package.json and scripts/md2html/build-src.sh changes from this PR.
I'll extract them to their own PR targeting main.

[duncanbeevers]

@ralfhandl The md2html.js versions between main and dev already have some differences. I'll try to keep my changes targeting main as small as possible, but I'll admit it's a bit confusing having the branches out of sync like this.

[ralfhandl]

@ralfhandl I've removed the package.json and scripts/md2html/build-src.sh changes from this PR.
I'll extract them to their own PR targeting main.

Actually we don't need/want build-src on main, so we need a PR targeting dev once #4344 is merged that

• changes the build-src script in package.json to use the improved md2html/build.sh
• removes the now obsolete md2html/build-src.sh

[ralfhandl]

@duncanbeevers This PR only contains variations of changes that have already been merged to dev: do you want to close it?

We still need

a second PR targeting dev changing package.json and removing build-src.sh, which can then be merged and synced to the v3.*-dev branches

Would you like to create that second PR?