feat: add documentation (#8593)

.eslintignore

@@ -1,7 +1,6 @@
 assets/
 build/
 coverage/
-doclint/
 lib/
 tsconfig.tsbuildinfo
 vendor/

.github/workflows/ci.yml

@@ -16,6 +16,67 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  check-docs:
+    name: Check documentation
+    runs-on: ubuntu-latest
+    outputs:
+      needs_deploying: ${{ steps.needs_deploying.outputs.value }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Set up Node.js
+        uses: actions/setup-node@v3.3.0
+        with:
+          cache: npm
+      - name: Cache Chromium binary directory
+        uses: actions/cache@v3
+        with:
+          path: .local-chromium
+          key: ${{ runner.os }}-chromium-${{ hashFiles('src/revisions.ts') }}
+      - name: Install dependencies
+        run: npm ci
+      - name: Build
+        run: npm run docs
+      - name: Check if autogenerated docs differ
+        run: $(git diff) || exit 1
+      - name: Check if docs need to be deployed
+        id: needs_deploying
+        run: |
+          if [[ $(git diff @~ -- ./docs ./website) ]]; then
+            needs_deploying=true
+          else
+            needs_deploying=false
+          fi
+          echo "::set-output name=value::$needs_deploying"
+
+  deploy-docs:
+    needs: check-docs
+    name: Deploy docs (if needed)
+    if: ${{ needs.check-docs.outputs.needs_deploying == 'true' && github.event_name != 'pull_request' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 2
+      - name: Set up Node.js
+        uses: actions/setup-node@v3.3.0
+        with:
+          cache: npm
+      - name: Install dependencies
+        working-directory: ./website
+        run: npm ci
+      - name: Build website
+        working-directory: ./website
+        run: npm run build
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./website/build
+          user_name: release-please[bot]
+          user_email: 55107282+release-please[bot]@users.noreply.github.com
+
   linux:
     # https://github.com/actions/virtual-environments#available-environments
     runs-on: ubuntu-latest
@@ -51,9 +112,6 @@ jobs:
         run: |
           npm run test:pinned-deps
           npm run lint
-          # Skipping as it's flakey and we are not currently using the new documentation site in the wild yet.
-          # See https://github.com/puppeteer/puppeteer/issues/7710 for more info
-          # npm run generate:docs
           npm run test:protocol-revision
           npm run test:types
 

.github/workflows/pre-release.yml

@@ -21,10 +21,16 @@ jobs:
       - name: Build
         run: |
           node utils/generate_version_file.js
-          IS_RELEASE=1 npm run doc
+          npm run docs
+      - name: Version docs
+        working-directory: ./website
+        run: |
+          npm install
+          npm run docusaurus docs:version $(jq -r .version ../package.json)
       - name: Commit
         run: |
           git config --global user.name 'release-please[bot]'
           git config --global user.email '55107282+release-please[bot]@users.noreply.github.com'
-          git commit -am 'chore: freeze version on docs'
+          git add .
+          git commit -m 'chore: generated versioned docs'
           git push --no-verify

.github/workflows/publish.yml

@@ -36,25 +36,3 @@ jobs:
           npm config set registry 'https://wombat-dressing-room.appspot.com/'
           npm config set '//wombat-dressing-room.appspot.com/:_authToken' '${NPM_TOKEN}'
           npm publish
-
-  post-publish:
-    needs: publish
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      pull-requests: write
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-        with:
-          ref: main
-      - name: Install dependencies
-        run: npm install
-      - name: Build main docs
-        run: npm run doc
-      - name: Commit
-        run: |
-          git config --global user.email "55107282+release-please[bot]@users.noreply.github.com"
-          git config --global user.name "release-please[bot]"
-          git commit -am "chore: unfreeze version on docs"
-          git push

.gitignore

@@ -1,19 +1,33 @@
-.DS_Store
-.vscode
-/.dev_profile*
-/.local-chromium/
-/.local-firefox/
-/test/output-*/
-build/
+# Dependencies
+node_modules
+
+# Production
+build
+lib
+
+# Generated files
 coverage
-coverage/
-doclint/
-docs-api-json/
-docs/api.html
-lib/
-node_modules/
-package-lock.json
+tsconfig.tsbuildinfo
 puppeteer.api.json
 puppeteer*.tgz
-tsconfig.tsbuildinfo
-yarn.lock
+yarn.lock
+.docusaurus
+.cache-loader
+.local-chromium
+.local-firefox
+test/output-*/
+.dev_profile*
+
+# IDE Artifacts
+.vscode
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

.prettierignore

@@ -4,7 +4,6 @@ assets/
 build/
 CHANGELOG.md
 coverage/
-doclint/
 lib/
 node_modules/
 package-lock.json
@@ -13,4 +12,6 @@ test/assets/
 tsconfig.tsbuildinfo
 vendor/
 yarn.lock
-puppeteer.api.json
+puppeteer.api.json
+website/
+docs/