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).
This commit is contained in:
Eric Arellano
GitHub
parent
fac0c0115d
commit
2c82c0dc6a
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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}"];
|
||||
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.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) {
|
||||
globs.push("!docs/api/qiskit/release-notes/*");
|
||||
if (args.historicalApis) {
|
||||
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}");
|
||||
|
|
|
|||
Loading…
Reference in New Issue