Merge docs into main prior to v10 release (#1335)

* switch typedoc to using patched branch to fix anchors

* try again

* try again

* Update imports.md

* move website-only deps to website/package.json

* update main<->docs merge instructions in CONTRIBUTING.md

* fix potential confusion about docs<->main merge strategy

.github/workflows/website.yml

@@ -17,7 +17,8 @@ jobs:
         with:
           node-version: 14
       # Render typedoc
-      - run: npm install && ./node_modules/.bin/typedoc
+      # Using custom branch to workaround: https://github.com/TypeStrong/typedoc/issues/1585
+      - run: npm install && git clone --depth 1 https://github.com/cspotcode/typedoc --branch patch-2 && pushd typedoc && npm install && npm run build || true && popd && ./typedoc/bin/typedoc
       # Render docusaurus and deploy website
       - run: |
           set -euo pipefail

CONTRIBUTING.md

@@ -29,7 +29,7 @@ Docs for the latest stable release live in a `docs` branch.  The "Edit this page
 branch so that the website can be improved in parallel with new feature work.
 
 Docs changes for unreleased features are merged to `main` in the same PR which implements the feature, adds tests, etc.
-When we release a new version, we merge `main` into `docs` and `docs` into `main`, unifying the two.
+When we release a new version, we merge `main` with `docs`, unifying the two.
 
 ```shell
 cd ./website
@@ -44,11 +44,14 @@ This site was used to generate the favicon from a high-res PNG export of the SVG
 
 We publish using `np`: https://npm.im/np
 
-1. Merge `docs` into `main`
+1. Merge `docs` into `main` using a pull request, ensuring a consistent squash-merge
 2. Rebuild the README (see instructions above, necessary because npmjs.com renders the readme)
 3. Publish with `np`
 4. Add changelog to the Github Release; match formatting from previous releases
-5. Merge `main` into `docs` (this automatically rebuilds the website)
+5. Move `docs` branch to head of `main`
+  - this rebuilds the website
+  - `git push --force origin main:docs`
+  - avoids merge messiness due to earlier squash-merge from `docs` to `main`
 6. If tsconfig schema has changed, send a pull request to schemastore.  [Example](https://github.com/SchemaStore/schemastore/pull/1208)
 
 ## APIExtractor

package.json

@@ -161,11 +161,9 @@
     "@tsconfig/node12": "^1.0.7",
     "@tsconfig/node14": "^1.0.0",
     "@tsconfig/node16": "^1.0.1",
-    "@types/js-yaml": "^4.0.0",
     "arg": "^4.1.0",
     "create-require": "^1.1.0",
     "diff": "^4.0.1",
-    "js-yaml": "^4.0.0",
     "make-error": "^1.1.1",
     "source-map-support": "^0.5.17",
     "yn": "3.1.1"

website/docs/imports.md

@@ -15,7 +15,7 @@ Here is a brief comparison of the two.
 
 ## CommonJS
 
-Transforming to CommonJS is typically simpler and more widely supported because it is older.  You must remove or set [`"type": "commonjs"`](https://nodejs.org/api/packages.html#packages_type) in `package.json` and [`"module": "CommonJS"`](https://www.typescriptlang.org/tsconfig/#module) in `tsconfig.json`.
+Transforming to CommonJS is typically simpler and more widely supported because it is older.  You must remove [`"type": "module"`](https://nodejs.org/api/packages.html#packages_type) from `package.json` and set [`"module": "CommonJS"`](https://www.typescriptlang.org/tsconfig/#module) in `tsconfig.json`.
 
 ```json title="package.json"
 {

website/package.json

@@ -17,7 +17,9 @@
     "@docusaurus/preset-classic": "2.0.0-alpha.75",
     "@docusaurus/theme-search-algolia": "^2.0.0-alpha.75",
     "@mdx-js/react": "^1.6.21",
+    "@types/js-yaml": "^4.0.0",
     "clsx": "^1.1.1",
+    "js-yaml": "^4.0.0",
     "react": "^16.8.4",
     "react-dom": "^16.8.4",
     "remark": "^13.0.0",

website/yarn.lock

@@ -2609,6 +2609,11 @@
   resolved "https://registry.yarnpkg.com/@types/html-minifier-terser/-/html-minifier-terser-5.1.1.tgz#3c9ee980f1a10d6021ae6632ca3e79ca2ec4fb50"
   integrity sha512-giAlZwstKbmvMk1OO7WXSj4OZ0keXAcl2TQq4LWHiiPH2ByaH7WeUzng+Qej8UPxxv+8lRTuouo0iaNDBuzIBA==
 
+"@types/js-yaml@^4.0.0":
+  version "4.0.1"
+  resolved "https://registry.yarnpkg.com/@types/js-yaml/-/js-yaml-4.0.1.tgz#5544730b65a480b18ace6b6ce914e519cec2d43b"
+  integrity sha512-xdOvNmXmrZqqPy3kuCQ+fz6wA0xU5pji9cd1nDrflWaAWtYLLGk5ykW0H6yg5TVyehHP1pfmuuSaZkhP+kspVA==
+
 "@types/json-schema@*", "@types/json-schema@^7.0.5", "@types/json-schema@^7.0.6":
   version "7.0.7"
   resolved "https://registry.yarnpkg.com/@types/json-schema/-/json-schema-7.0.7.tgz#98a993516c859eb0d5c4c8f098317a9ea68db9ad"