feat: add documentation

puppeteer · Jun 28, 2022 · c9591fd · c9591fd
1 parent 7a22f95
commit c9591fd
Show file tree

Hide file tree

Showing 763 changed files with 50,170 additions and 7,488 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -16,239 +16,108 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  linux:
-    # https://github.com/actions/virtual-environments#available-environments
+  check-docs:
+    name: Check documentation
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        # Include all major maintenance + active LTS + current Node.js versions.
-        # https://github.com/nodejs/Release#release-schedule
-        node: [14, 16, 18]
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 2
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v3.3.0
-        with:
-          node-version: ${{ matrix.node }}
-
-      - name: Install dependencies
-        run: |
-          sudo apt-get install xvfb
-          # Ensure both a Chromium and a Firefox binary are available.
-          PUPPETEER_PRODUCT=firefox npm install
-          npm install
-          ls .local-chromium .local-firefox
-
-      - name: Build
-        run: |
-          npm run build
-
-      - name: Run code checks
-        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
-
-      - name: Run commit lint
-        run: |
-          npm run commitlint
-        if: github.event_name != 'pull_request'
-
-      - name: Run unit tests with coverage
-        uses: nick-invision/retry@v2
-        env:
-          CHROMIUM: true
-        with:
-          max_attempts: 3
-          command: xvfb-run --auto-servernum npm run test:unit:coverage
-          timeout_minutes: 10
-
-      - name: Run unit tests on Firefox
-        uses: nick-invision/retry@v2
-        env:
-          FIREFOX: true
-          MOZ_WEBRENDER: 0
-        with:
-          max_attempts: 3
-          timeout_minutes: 10
-          command: xvfb-run --auto-servernum npm run test:unit:firefox
-
-      - name: Test bundling and installation
-        env:
-          CHROMIUM: true
-        run: |
-          # Note: this modifies package.json to test puppeteer-core.
-          npm run test:install
-          # Undo those changes.
-          git checkout --force
-
-  macos:
-    # https://github.com/actions/virtual-environments#available-environments
-    runs-on: macos-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:
-          # Test only the oldest maintenance LTS Node.js version.
-          # https://github.com/nodejs/Release#release-schedule
-          node-version: 14
-
+          cache: npm
       - name: Install dependencies
-        run: |
-          # Test platform-specific browser binary fetching for both
-          # Chromium and Firefox.
-          PUPPETEER_PRODUCT=firefox npm install
-          npm install
-          ls .local-chromium .local-firefox
-
+        run: npm ci
       - name: Build
-        run: |
-          npm run build
+        run: npm run docs
+      - name: Diff docs
+        run: $(git diff) || exit 1
 
-      - name: Run unit tests
-        env:
-          CHROMIUM: true
-        run: |
-          npm run test:unit
-
-      - name: Run unit tests on Firefox
-        uses: nick-invision/retry@v2
-        with:
-          max_attempts: 3
-          timeout_minutes: 10
-          command: npm run test:unit:firefox
-
-  windows:
-    # https://github.com/actions/virtual-environments#available-environments
-    runs-on: windows-latest
+  check-code:
+    name: Check code
+    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:
-          # Test only the oldest maintenance LTS Node.js version.
-          # https://github.com/nodejs/Release#release-schedule
-          node-version: 14
-
+          cache: npm
       - name: Install dependencies
+        run: npm ci
+      - name: Lint and check code
         run: |
-          # Test platform-specific browser binary fetching for both
-          # Chromium and Firefox.
-          $env:PUPPETEER_PRODUCT='firefox'
-          npm install
-          Remove-Item Env:\PUPPETEER_PRODUCT
-          npm install
-          Get-ChildItem -Path .local-chromium,.local-firefox
-
-      - name: Build
-        run: |
-          npm run build
-
-      - name: Run unit tests
-        env:
-          CHROMIUM: true
-        run: |
-          npm run test:unit
-
-      - name: Run unit tests on Firefox
-        uses: nick-invision/retry@v2
-        continue-on-error: true
-        env:
-          FIREFOX: true
-          MOZ_WEBRENDER: 0
-        with:
-          max_attempts: 3
-          timeout_minutes: 10
-          command: npm run test:unit:firefox
+          npm run lint
+          npm run check
+      - name: Lint commits (only for push to main)
+        run: npm run commitlint
+        if: github.event_name != 'pull_request'
 
-  linux-headful:
-    # https://github.com/actions/virtual-environments#available-environments
+  linux:
+    name: Linux runtime tests
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        # Include a current Node.js version.
+        # Include all major maintenance + active LTS + current Node.js versions.
         # https://github.com/nodejs/Release#release-schedule
-        node: [18]
+        node: [14, 16, 18]
     steps:
       - name: Checkout
         uses: actions/checkout@v3
-        with:
-          fetch-depth: 2
-
       - name: Set up Node.js
         uses: actions/setup-node@v3.3.0
         with:
           node-version: ${{ matrix.node }}
-      - name: Install dependencies
-        run: |
-          sudo apt-get install xvfb
-          # Ensure both a Chromium and a Firefox binary are available.
-          PUPPETEER_PRODUCT=firefox npm install
-          npm install
-          ls .local-chromium .local-firefox
-
+          cache: npm
+      - name: Install with Chrome
+        run: npm ci
+      - name: Install with Firefox
+        env:
+          PUPPETEER_PRODUCT: 'firefox'
+        run: npm ci
+      - name: Install testing dependencies
+        run: sudo apt-get install xvfb
       - name: Build
-        run: |
-          npm run build
-      - name: Run unit tests in headful mode
+        run: npm run build
+      - name: Run unit tests with coverage
         uses: nick-invision/retry@v2
-        env:
-          CHROMIUM: true
-          HEADLESS: false
         with:
-          max_attempts: 1
-          command: xvfb-run --auto-servernum npm run test:unit
+          max_attempts: 3
+          command: xvfb-run --auto-servernum npm run test:coverage
           timeout_minutes: 10
 
-  linux-chrome-headless:
-    runs-on: ${{ matrix.os }}
+  other-oses:
+    name: ${{ matrix.os.name }} runtime tests
+    runs-on: ${{ matrix.os.release }}
     strategy:
       matrix:
-        # https://github.com/actions/virtual-environments#available-environments
-        os: [ubuntu-latest]
-        # https://github.com/nodejs/Release#release-schedule
-        node: [18]
+        os:
+          - name: 'macOS'
+            release: 'macos-latest'
+          - name: 'Windows'
+            release: 'windows-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:
-          node-version: ${{ matrix.node }}
-      - name: Install dependencies
-        run: |
-          sudo apt-get install xvfb
-          # Ensure both a Chromium and a Firefox binary are available.
-          PUPPETEER_PRODUCT=firefox npm install
-          npm install
-          ls .local-chromium .local-firefox
+          # Test only the oldest maintenance LTS Node.js version.
+          # https://github.com/nodejs/Release#release-schedule
+          node-version: 14
+      - name: Install with Chrome
+        run: npm ci
+      - name: Install with Firefox
+        env:
+          PUPPETEER_PRODUCT: 'firefox'
+        run: npm ci
       - name: Build
-        run: |
-          npm run build
-      - name: Run unit tests
+        run: npm run build
+      - name: Run unit tests with coverage
         uses: nick-invision/retry@v2
-        env:
-          CHROMIUM: true
         with:
-          max_attempts: 1
-          command: xvfb-run --auto-servernum npm run test:unit:chrome-headless
+          max_attempts: 3
           timeout_minutes: 10
+          command: npm run test:coverage
diff --git a/.github/workflows/pre-release.yml b/.github/workflows/pre-release.yml
@@ -7,6 +7,7 @@ on:
 
 jobs:
   pre-release:
+    name: Attach pre-release artifacts
     if: "startsWith(github.event.head_commit.message, 'chore(main): release')"
     runs-on: ubuntu-latest
     permissions:
@@ -17,11 +18,10 @@ jobs:
         with:
           ssh-key: ${{ secrets.SSH_PRIVATE_KEY }}
       - name: Install dependencies
-        run: npm install
+        run: npm ci
       - name: Build
         run: |
           node utils/generate_version_file.js
-          IS_RELEASE=1 npm run doc
       - name: Commit
         run: |
           git config --global user.name 'release-please[bot]'

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -6,15 +6,16 @@ on:
       - v*
 
 jobs:
-  publish:
+  npm-publish:
+    name: Publish to NPM
     runs-on: ubuntu-latest
     permissions:
       contents: read
     steps:
       - name: Checkout
         uses: actions/checkout@v3
       - name: Install dependencies
-        run: npm install
+        run: npm ci
       - name: Build puppeteer
         run: npm run build
       - name: Publish puppeteer
@@ -37,7 +38,8 @@ jobs:
           npm config set '//wombat-dressing-room.appspot.com/:_authToken' '${NPM_TOKEN}'
           npm publish
 
-  post-publish:
+  deploy-docs:
+    name: Deploy documentation
     needs: publish
     runs-on: ubuntu-latest
     permissions:
@@ -48,23 +50,23 @@ jobs:
         uses: actions/checkout@v3
         with:
           ref: main
-      - name: Install dependencies
-        run: npm install
-      - name: Build main docs
-        run: npm run doc
-      - name: Commit
+      - name: Generate docs
+        working-directory: ./website
+        run: npm run docs
+      - name: Version docs
+        working-directory: ./website
+        run: npm run docusaurus docs:version ${GITHUB_REF#refs/*/v}
+      - name: Commit to main
         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"
-      - name: Create PR
-        uses: peter-evans/create-pull-request@v4
+          git add .
+          git commit -m "chore: generate v${GITHUB_REF#refs/*/v} docs"
+          git push
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
         with:
-          token: ${{secrets.PR_PAT}}
-          committer: 'release-please[bot] <55107282+release-please[bot]@users.noreply.github.com>'
-          author: 'release-please[bot] <55107282+release-please[bot]@users.noreply.github.com>'
-          title: 'chore: unfreeze version on docs'
-          body: ''
-          labels: automated pr
-          branch: create-pull-request/unfreeze
-          delete-branch: true
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./website/build
+          user_name: release-please[bot]
+          user_email: 55107282+release-please[bot]@users.noreply.github.com