Improve release script & enable versioning documentation (#1521)

* Add version selection page

* Update the CDN urls in the documentation

* Generate new version and publish documentation in release script

* Update CDN urls when NEXT_VERSION is not provided

* Remove bower-related from release script

* Improve instructions running on the release branch 

and without next version

* Add a suffix to the branch name

* Update CSS stylesheet replacement

* Update release.sh

* Change npm to Yarn

* Fix calling `version` script

* Run `prestart` in `version`

* Wrap `Latest Version` descriptions with p tag

* Explicitly specify files to commit in the website

release.sh

@@ -28,8 +28,13 @@ usage() {
     echo " When releasing a new major version:"
     echo "   ./release.sh 0.7.0 0.8.0"
     echo ""
-    echo "You may omit NEXT_VERSION in order to avoid creating a commit on"
+    echo "You may omit NEXT_VERSION in order to avoid updating the version field"
-    echo "the branch from which the release was created.  Not recommended."
+    echo "of the package.json."
+    echo ""
+    echo "Run this on the master branch, if you have permission to directly push"
+    echo "to the master branch. Otherwise, create a branch with the version number"
+    echo "as its name and a suffix to distinguish from its tag, e.g.,"
+    echo "'v1.0.0-release', and run this on it."
     exit $1
 }
 
@@ -98,56 +103,87 @@ git checkout "$BRANCH"
 git pull
 git checkout --detach
 
-# Edit package.json and bower.json to the right version (see
+# Edit package.json to the right version (see
 # http://stackoverflow.com/a/22084103 for why we need the .bak file to make
 # this mac & linux compatible)
 sed -i.bak -E 's|"version": "[^"]+",|"version": "'$VERSION'",|' package.json
 rm -f package.json.bak
 
-# Build generated files and add them to the repository (for bower)
+# Build generated files and add them to the repository
 git clean -fdx dist
 yarn dist
 sed -i.bak -E '/^\/dist\/$/d' .gitignore
 rm -f .gitignore.bak
 git add .gitignore dist/
 
-# Update the version number in CDN URLs included in the README files,
+# Edit docs to use CSS from CDN (#1520)
+# grep -l '{@stylesheet: static/katex.min.css}' docs/*.md | xargs sed -i.bak \
+#     's|{@stylesheet: static/katex.min.css}|<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@./dist/katex.min.css" integrity="sha256-katex.min.css" crossorigin="anonymous"/>|'
+
+# Update the version number in CDN URLs included in the README and the documentation,
 # and regenerate the Subresource Integrity hash for these files.
-node update-sri.js "${VERSION}" README.md contrib/*/README.md dist/README.md
+node update-sri.js "${VERSION}" README.md contrib/*/README.md dist/README.md \
+    docs/*.md docs/*.md.bak website/pages/index.html
+
+# Generate a new version of the docs and publish the website
+pushd website
+yarn run version "${VERSION}"
+
+# Restore docs to use local built CSS
+# for file in ../docs/*.md.bak; do
+#     mv -f "$file" "${file%.bak}"
+# done
+
+USE_SSH=true yarn publish-gh-pages
+popd
 
 # Make the commit and tag, and push them.
-git add package.json bower.json README.md contrib/*/README.md dist/README.md
+git add package.json README.md contrib/*/README.md dist/README.md \
+    docs/*.md website/pages/index.html website/versioned_docs/ \
+    website/versioned_sidebars/ website/versions.json
 git commit -n -m "v$VERSION"
 git diff --stat --exit-code # check for uncommitted changes
 git tag -a "v$VERSION" -m "v$VERSION"
 git push origin "v$VERSION"
 
-# Update npm (bower and cdnjs update automatically)
+# Update npm (cdnjs update automatically)
-yarn publish
+yarn publish --new-version "${VERSION}"
+
+# Go back to original branch to bump
+git checkout "$BRANCH"
 
 if [ ! -z "$NEXT_VERSION" ]; then
-    # Go back to original branch to bump
+    # Edit package.json to the next version
-    git checkout "$BRANCH"
-
-    # Edit package.json and bower.json to the right version
     sed -i.bak -E 's|"version": "[^"]+",|"version": "'$NEXT_VERSION'-pre",|' package.json
     rm -f package.json.bak
-
+    git add package.json
-    # Refer to the just-released version in the documentation of the
-    # development branch, too.  Most people will read docs on master.
-    git checkout "v${VERSION}" -- README.md contrib/*/README.md
-
-    git add package.json bower.json
-    git commit -n -m "Bump $BRANCH to v$NEXT_VERSION-pre"
-    git push origin "$BRANCH"
-
-    # Go back to the tag which has katex.tar.gz and katex.zip
-    git checkout "v$VERSION"
 fi
 
+# Refer to the just-released version in the documentation of the
+# development branch, too.  Most people will read docs on master.
+git checkout "v${VERSION}" -- README.md contrib/*/README.md docs/*.md website/
+
+if [[ -z "$NEXT_VERSION" ]]; then
+    git commit -n -m "Release v$VERSION"
+else
+    git commit -n -m "Bump $BRANCH to v$NEXT_VERSION-pre"
+fi
+
+git push origin "$BRANCH"
+
+# Go back to the tag which has katex.tar.gz and katex.zip
+git checkout "v$VERSION"
+
 echo ""
 echo "The automatic parts are done!"
-echo "Now all that's left is to create the release on github."
+
+if [[ $BRANCH != "master" ]]; then
+    echo "Now all that's left is to create a pull request against master from '$BRANCH'"
+    echo "and to create the release on github."
+else
+    echo "Now all that's left is to create the release on github."
+fi
+
 echo "Visit https://github.com/Khan/KaTeX/releases/new?tag=v$VERSION to edit the release notes"
 echo "Don't forget to upload katex.tar.gz and katex.zip to the release!"
 

website/package.json

@@ -5,7 +5,7 @@
     "build": "npm run prestart && docusaurus-build",
     "publish-gh-pages": "npm run prestart && docusaurus-publish",
     "write-translations": "docusaurus-write-translations",
-    "version": "docusaurus-version",
+    "version": "npm run prestart && docusaurus-version",
     "rename-version": "docusaurus-rename-version"
   },
   "devDependencies": {

website/pages/en/versions.js

@@ -0,0 +1,111 @@
+/**
+ * Copyright (c) 2017-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+const fs = require('fs');
+const React = require('react');
+
+const {Container} = require('../../core/CompLibrary');
+
+const CWD = process.cwd();
+
+const {title, baseUrl, repoUrl} = require(`${CWD}/siteConfig.js`);
+const versions = fs.existsSync(`${CWD}/versions.json`)
+    ? require(`${CWD}/versions.json`) : [];
+
+function Versions(props) {
+    const latestVersion = versions[0];
+    const language = props.language && props.language !== 'en' ?
+        props.language + '/' : '';
+    return (
+        <div className="docMainWrapper wrapper">
+        <Container className="mainContainer versionsContainer">
+          <div className="post">
+            <header className="postHeader">
+              <h1>{title} Versions</h1>
+            </header>
+            <h3 id="latest">Current version (Stable)</h3>
+            <p>Latest version of KaTeX.</p>
+            <table className="versions">
+              <tbody>
+                <tr>
+                  <th>{latestVersion}</th>
+                  <td>
+                    <a
+                      href={`${baseUrl}docs/${language}node.html`}>
+                      Documentation
+                    </a>
+                  </td>
+                  <td>
+                    <a href={`${repoUrl}/releases/tag/v${latestVersion}`}>
+                      Release Notes
+                    </a>
+                  </td>
+                </tr>
+              </tbody>
+            </table>
+            <h3 id="rc">Latest Version</h3>
+            <p>
+              Here you can find the latest documentation and unreleased code.
+            </p>
+            <table className="versions">
+              <tbody>
+                <tr>
+                  <th>master</th>
+                  <td>
+                    <a
+                      href={`${baseUrl}docs/${language}next/node.html`}>
+                      Documentation
+                    </a>
+                  </td>
+                  <td>
+                    <a href={repoUrl}>Source Code</a>
+                  </td>
+                </tr>
+              </tbody>
+            </table>
+            <h3 id="archive">Past Versions</h3>
+            <p>
+              Here you can find documentation for previous versions of KaTeX.
+            </p>
+            <table className="versions">
+              <tbody>
+                {versions.map(
+                  version =>
+                    version !== latestVersion && (
+                      <tr key={version}>
+                        <th>{version}</th>
+                        <td>
+                          <a
+                            href={`${baseUrl}docs/${
+                              language
+                            }${version}/node.html`}>
+                            Documentation
+                          </a>
+                        </td>
+                        <td>
+                          <a href={`${repoUrl}/releases/tag/v${version}`}>
+                            Release Notes
+                          </a>
+                        </td>
+                      </tr>
+                    )
+                )}
+              </tbody>
+            </table>
+            <p>
+              You can find past versions of KaTeX on{' '}
+              <a href={`${repoUrl}/releases`}>GitHub</a>.
+            </p>
+          </div>
+        </Container>
+      </div>
+    );
+}
+
+Versions.title = 'Versions';
+
+module.exports = Versions;