diff --git a/.github/workflows/api-checks.yml b/.github/workflows/api-checks.yml index e9a5c3b56d0..39f7de03dbd 100644 --- a/.github/workflows/api-checks.yml +++ b/.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 diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 94fadf8de44..ede2b038e6d 100644 --- a/.github/workflows/main.yml +++ b/.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 diff --git a/.github/workflows/weekly-checks.yml b/.github/workflows/weekly-checks.yml new file mode 100644 index 00000000000..52fad89e6c9 --- /dev/null +++ b/.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 diff --git a/README.md b/README.md index 21ac41c8b1b..07963eea9a7 100644 --- a/README.md +++ b/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 -translations. +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. ## Format TypeScript files diff --git a/scripts/commands/checkPagesRender.ts b/scripts/commands/checkPagesRender.ts index 0d0a5980654..d3d011033e3 100644 --- a/scripts/commands/checkPagesRender.ts +++ b/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 { } async function determineFilePaths(args: Arguments): Promise { - const globs = ["docs/**/*.{ipynb,md,mdx}"]; - if (!args.currentApis) { - globs.push("!docs/api/{qiskit,qiskit-ibm-provider,qiskit-ibm-runtime}/*"); + const globs = []; + if (args.fromFile) { + const content = await fs.readFile(args.fromFile, "utf-8"); + globs.push(...content.split("\n").filter((entry) => entry)); + } + + if (args.nonApi) { + globs.push( + "docs/support.mdx", + "docs/{build,run,start,transpile,verify}/*.{ipynb,md,mdx}", + "docs/api/migration-guides/**/*.{ipynb,md,mdx}", + ); + } + if (args.currentApis) { + globs.push( + "docs/api/{qiskit,qiskit-ibm-provider,qiskit-ibm-runtime}/*.{ipynb,md,mdx}", + ); } - if (!args.historicalApis) { + if (args.historicalApis) { globs.push( - "!docs/api/{qiskit,qiskit-ibm-provider,qiskit-ibm-runtime}/[0-9]*/*", + "docs/api/{qiskit,qiskit-ibm-provider,qiskit-ibm-runtime}/[0-9]*/*.{ipynb,md,mdx}", ); } - if (!args.devApis) { + if (args.devApis) { globs.push( - "!docs/api/{qiskit,qiskit-ibm-provider,qiskit-ibm-runtime}/dev/*", + "docs/api/{qiskit,qiskit-ibm-provider,qiskit-ibm-runtime}/dev/*.{ipynb,md,mdx}", ); } - if (!args.qiskitReleaseNotes) { - globs.push("!docs/api/qiskit/release-notes/*"); + if (args.qiskitReleaseNotes) { + globs.push("docs/api/qiskit/release-notes/*.{ipynb,md,mdx}"); } if (args.translations) { globs.push("translations/**/*.{ipynb,md,mdx}");