Pages render check only runs on changed files (#913)

Closes https://github.com/Qiskit/documentation/issues/886. As explained
there, it's safe to only run this check on changed files because whether
a page renders is independent from all the other pages.

We use a weekly cron job, though, to check all pages. That reduces our
risk from things like the docs preview Docker image changing on us and
resulting in some pages now failing to render.

--

This PR also stops checking external links in API docs builds and
instead moves the check to the new weekly cron job. Relates to
https://github.com/Qiskit/documentation/issues/876.

Per https://github.com/Qiskit/documentation/pull/372, it's annoying to
check external links in CI because it can be flaky
(https://github.com/Qiskit/documentation/issues/823).

.github/workflows/api-checks.yml

@@ -13,9 +13,6 @@
 name: API checks
 on:
   workflow_dispatch:
-  schedule:
-    - cron: "0 0 * * 0,2,4" # Every Sunday, Tuesday, and Thursday at midnight UTC
-
   pull_request:
     paths:
       - "docs/api/qiskit/**/*"
@@ -26,7 +23,7 @@ on:
       - "scripts/lib/links/ignores.ts"
 
 jobs:
-  link-checker:
+  api-checks:
     runs-on: ubuntu-latest
     if: github.repository_owner == 'Qiskit'
     steps:
@@ -37,7 +34,7 @@ jobs:
           node-version: 18
       - name: Install Node.js dependencies
         run: npm ci
-      - name: Check links
+      - name: Check internal links
         run: >
           npm run check:links --
           --qiskit-release-notes
@@ -45,27 +42,3 @@ jobs:
           --dev-apis
           --historical-apis
           --skip-broken-historical
-          --external
-
-  pages-render:
-    runs-on: ubuntu-latest
-    if: github.repository_owner == 'Qiskit'
-    steps:
-      - uses: actions/checkout@v4
-      - name: Set up Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: 18
-      - name: Install Node.js dependencies
-        run: npm ci
-      - name: Start local Docker preview
-        run: |
-          ./start &
-          sleep 20
-      - name: Check API pages render
-        run: >
-          npm run check-pages-render --
-          --qiskit-release-notes
-          --current-apis
-          --dev-apis
-          --historical-apis

.github/workflows/main.yml

@@ -30,7 +30,7 @@ jobs:
         run: npm run check:metadata
       - name: Spellcheck
         run: npm run check:spelling
-      - name: Link checker
+      - name: Internal link checker
         run: npm run check:links
       - name: Formatting
         run: npm run check:fmt
@@ -39,9 +39,19 @@ jobs:
       - name: Infrastructure tests
         run: npm test
 
+      - name: Get all changed docs files
+        id: changed-docs-files
+        uses: tj-actions/changed-files@af2816c65436325c50621100d67f6e853cd1b0f1
+        with:
+          files: docs/**/*.{md,mdx,ipynb}
+          separator: "\n"
       - name: Start local Docker preview
+        if: steps.changed-docs-files.outputs.any_changed == 'true'
         run: |
           ./start &
           sleep 20
       - name: Check that pages render
-        run: npm run check-pages-render
+        if: steps.changed-docs-files.outputs.any_changed == 'true'
+        run: |
+          echo "${{ steps.changed-docs-files.outputs.all_changed_files }}" > changed.txt
+          npm run check-pages-render -- --from-file changed.txt

.github/workflows/weekly-checks.yml

@@ -0,0 +1,63 @@
+# This code is a Qiskit project.
+#
+# (C) Copyright IBM 2024.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+name: Weekly checks
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 0 * * 0" # Every Sunday at midnight UTC
+
+jobs:
+  pages-render:
+    runs-on: ubuntu-latest
+    if: github.repository_owner == 'Qiskit'
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+      - name: Install Node.js dependencies
+        run: npm ci
+      - name: Start local Docker preview
+        run: |
+          ./start &
+          sleep 20
+      - name: Check all pages render
+        run: >
+          npm run check-pages-render --
+          --non-api
+          --qiskit-release-notes
+          --current-apis
+          --dev-apis
+          --historical-apis
+
+  external-link-checker:
+    runs-on: ubuntu-latest
+    if: github.repository_owner == 'Qiskit'
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+      - name: Install Node.js dependencies
+        run: npm ci
+      - name: Check external links
+        run: >
+          npm run check:links --
+          --qiskit-release-notes
+          --current-apis
+          --dev-apis
+          --historical-apis
+          --skip-broken-historical
+          --external

README.md

@@ -260,12 +260,11 @@ It's possible to write broken pages that crash when loaded. This is usually due
 To check that all the non-API docs render:
 
 1. Start up the local preview with `./start` by following the instructions at [Preview the docs locally](#preview-the-docs-locally)
-2. In a new tab, `npm run check-pages-render`
+2. In a new tab, `npm run check-pages-render -- --non-api`
 
-You can also check that API docs and translations render by using any of these arguments: `npm run check-pages-render -- --qiskit-release-notes --current-apis --dev-apis --historical-apis --translations`. Warning that this is exponentially slower.
+You can also check that API docs and translations render by using any of these arguments: `npm run check-pages-render -- --non-api --qiskit-release-notes --current-apis --dev-apis --historical-apis --translations`. Warning that this is exponentially slower.
 
-CI will check on every PR that non-API docs correctly render. We also run a nightly cron job to check the API docs and
+CI will check on every PR that any changed files render correctly. We also run a weekly cron job to check that every page renders correctly.
-translations.
 
 ## Format TypeScript files
 

scripts/commands/checkPagesRender.ts

@@ -10,6 +10,8 @@
 // copyright notice, and modified files need to carry a notice indicating
 // that they have been altered from the originals.
 
+import fs from "fs/promises";
+
 import { globby } from "globby";
 import yargs from "yargs/yargs";
 import { hideBin } from "yargs/helpers";
@@ -20,6 +22,8 @@ const PORT = 3000;
 
 interface Arguments {
   [x: string]: unknown;
+  fromFile?: string;
+  nonApi: boolean;
   currentApis: boolean;
   devApis: boolean;
   historicalApis: boolean;
@@ -30,6 +34,17 @@ interface Arguments {
 const readArgs = (): Arguments => {
   return yargs(hideBin(process.argv))
     .version(false)
+    .option("from-file", {
+      type: "string",
+      normalize: true,
+      description:
+        "Read the file path for file paths and globs to check, like `docs/start/index.md`. Entries should be separated by a newline and should be valid file types (.md, .mdx, .ipynb).",
+    })
+    .option("non-api", {
+      type: "boolean",
+      default: false,
+      description: "Check all the non-API docs, like start/.",
+    })
     .option("current-apis", {
       type: "boolean",
       default: false,
@@ -137,22 +152,36 @@ async function validateDockerRunning(): Promise<void> {
 }
 
 async function determineFilePaths(args: Arguments): Promise<string[]> {
-  const globs = ["docs/**/*.{ipynb,md,mdx}"];
+  const globs = [];
-  if (!args.currentApis) {
+  if (args.fromFile) {
-    globs.push("!docs/api/{qiskit,qiskit-ibm-provider,qiskit-ibm-runtime}/*");
+    const content = await fs.readFile(args.fromFile, "utf-8");
+    globs.push(...content.split("\n").filter((entry) => entry));
   }
-  if (!args.historicalApis) {
+
+  if (args.nonApi) {
     globs.push(
-      "!docs/api/{qiskit,qiskit-ibm-provider,qiskit-ibm-runtime}/[0-9]*/*",
+      "docs/support.mdx",
+      "docs/{build,run,start,transpile,verify}/*.{ipynb,md,mdx}",
+      "docs/api/migration-guides/**/*.{ipynb,md,mdx}",
     );
   }
-  if (!args.devApis) {
+  if (args.currentApis) {
     globs.push(
-      "!docs/api/{qiskit,qiskit-ibm-provider,qiskit-ibm-runtime}/dev/*",
+      "docs/api/{qiskit,qiskit-ibm-provider,qiskit-ibm-runtime}/*.{ipynb,md,mdx}",
     );
   }
-  if (!args.qiskitReleaseNotes) {
+  if (args.historicalApis) {
-    globs.push("!docs/api/qiskit/release-notes/*");
+    globs.push(
+      "docs/api/{qiskit,qiskit-ibm-provider,qiskit-ibm-runtime}/[0-9]*/*.{ipynb,md,mdx}",
+    );
+  }
+  if (args.devApis) {
+    globs.push(
+      "docs/api/{qiskit,qiskit-ibm-provider,qiskit-ibm-runtime}/dev/*.{ipynb,md,mdx}",
+    );
+  }
+  if (args.qiskitReleaseNotes) {
+    globs.push("docs/api/qiskit/release-notes/*.{ipynb,md,mdx}");
   }
   if (args.translations) {
     globs.push("translations/**/*.{ipynb,md,mdx}");