ci: improve the release docs workflow (#254)

<!-- 👋 Hi, thanks for sending a PR to ts-api-utils! 💖.
Please fill out all fields below and make sure each item is true and [x]
checked.
Otherwise we may not be able to review your PR. -->

## PR Checklist

- [x] Addresses an existing open issue: fixes #191
- [x] That issue was marked as [`status: accepting
prs`](https://github.com/JoshuaKGoldberg/ts-api-utils/issues?q=is%3Aopen+is%3Aissue+label%3A%22status%3A+accepting+prs%22)
- [x] Steps in
[CONTRIBUTING.md](https://github.com/JoshuaKGoldberg/ts-api-utils/blob/main/.github/CONTRIBUTING.md)
were taken

## Overview

The same issue as RebeccaStevens/uom-types#55

## Before Merge

`gh-pages` branch need to be created. Create with: 

```sh
git switch --orphan gh-pages
git commit --allow-empty -m "initial docs" --no-verify
git push
```

---------

Co-authored-by: Josh Goldberg <git@joshuakgoldberg.com>

.eslintrc.cjs

@@ -106,6 +106,7 @@ module.exports = {
 			parser: "yaml-eslint-parser",
 			rules: {
 				"yml/file-extension": ["error", { extension: "yml" }],
+				"yml/no-empty-mapping-value": "off",
 				"yml/sort-keys": [
 					"error",
 					{

.github/workflows/docs-release.yml

@@ -0,0 +1,72 @@
+concurrency:
+  cancel-in-progress: true
+  group: Release Docs
+
+jobs:
+  deploy_docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: get gh-pages
+        uses: actions/checkout@v3
+        with:
+          ref: gh-pages
+
+      - uses: ./.github/actions/prepare
+
+      - name: Create a pages artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: ./docs/generated
+
+      - id: deployment
+        name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v2
+
+      - name: Store Coverage Badge
+        run: cp ./docs/generated/stable/coverage.svg /tmp/coverage.svg
+
+      - name: get gh-pages
+        uses: actions/checkout@v3
+        with:
+          ref: main
+
+      - name: Update Coverage Badge
+        run: cp /tmp/coverage.svg ./docs/coverage.svg
+
+      - id: coverage_changed
+        run: echo "coverage_changed=$(git status --porcelain -u | grep -c docs/coverage.svg)" >> "$GITHUB_OUTPUT"
+
+      - env:
+          COVERAGE_CHANGED: ${{ steps.coverage_changed.outputs.coverage_changed }}
+        id: push_coverage
+        run: echo "push_coverage=$(if [[ "$COVERAGE_CHANGED" != '0' ]] ; then echo '1' ; else echo '0' ; fi)" >> "$GITHUB_OUTPUT"
+
+      - if: steps.push_coverage.outputs.push_coverage != '0'
+        uses: ./.github/actions/unprotect-main
+        with:
+          ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
+
+      - if: steps.push_coverage.outputs.push_coverage != '0'
+        run: |
+          git add docs/coverage.svg
+          git commit -m "docs: update documentation coverage badge"
+          git push
+
+      - if: ${{ always() && steps.push_coverage.outputs.push_coverage != '0' }}
+        uses: ./.github/actions/protect-main
+        with:
+          ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
+
+name: Release Docs
+
+on:
+  push:
+    branches:
+      - gh-pages
+
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  id-token: write
+  pages: write

.github/workflows/docs-update.yml

@@ -0,0 +1,70 @@
+concurrency:
+  cancel-in-progress: false
+  group: Update Docs
+
+jobs:
+  update_docs:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the docs
+        uses: actions/checkout@v3
+        with:
+          ref: gh-pages
+
+      - name: Save old docs
+        run: tar -cvf /tmp/old-docs.tar ./docs/generated
+
+      - name: Checkout tag
+        uses: actions/checkout@v3
+        with:
+          clean: false # doesn't seem to work?? Hense use of tar.
+          ref: ${{ github.ref_name }}
+
+      - uses: ./.github/actions/prepare
+
+      - name: Restore old docs
+        run: |
+          mkdir -p ./docs/generated
+          tar -xf /tmp/old-docs.tar ./docs/generated -C ./docs/generated
+
+      - name: Build docs
+        run: pnpm run docs
+
+      - name: Save new docs
+        run: tar -cvf /tmp/new-docs.tar ./docs/generated
+
+      - name: Checkout the docs
+        uses: actions/checkout@v3
+        with:
+          clean: false # doesn't seem to work?? Hense use of tar.
+          ref: gh-pages
+
+      - uses: ./.github/actions/prepare
+
+      - name: Restore new docs
+        run: |
+          mkdir -p ./docs/generated
+          tar -xf /tmp/new-docs.tar ./docs/generated -C ./docs/generated
+
+      - continue-on-error: true
+        name: Commit
+        run: |
+          git add -f docs/generated
+          git commit -m "docs: update documentation"
+          git push
+
+name: Update Docs
+
+on:
+  push:
+    tags:
+      # https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string -- github doesn't like this regex??
+      - v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)
+      - v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-|\+)([a-zA-Z0-9]|-|+|\.)*
+
+permissions:
+  contents: write
+  id-token: write

.github/workflows/release.yml

@@ -32,20 +32,3 @@ jobs:
         uses: ./.github/actions/protect-main
         with:
           ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
-
-  release_docs:
-    if: needs.release.outputs.did_release != '0'
-    needs: release
-    uses: ./.github/workflows/release-docs.yml
-name: Release
-
-on:
-  push:
-    branches:
-      - main
-
-permissions:
-  contents: write
-  id-token: write
-
-  pages: write

knip.jsonc

@@ -1,6 +1,7 @@
 {
 	"$schema": "https://unpkg.com/knip@latest/schema.json",
 	"entry": ["src/index.ts!"],
+	"ignoreBinaries": ["find"],
 	"ignoreExportsUsedInFile": { "interface": true, "type": true },
 	"project": ["src/**/*.ts!"]
 }

package.json

@@ -30,7 +30,7 @@
 		"README.md"
 	],
 	"scripts": {
-		"build": "tsup",
+		"build": "tsup src/index.ts && cp lib/index.d.ts lib/index.d.cts",
 		"docs": "typedoc",
 		"docs:serve": "npx --yes http-server docs/generated",
 		"format": "prettier \"**/*\" --ignore-unknown",

typedoc.json

@@ -75,5 +75,8 @@
 		"Interface",
 		"Method",
 		"TypeAlias"
-	]
+	],
+	"versions": {
+		"makeRelativeLinks": true
+	}
 }