From d9fa5d183efee8a452c7dd0fef6e848d86e3817f Mon Sep 17 00:00:00 2001 From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> Date: Thu, 15 Feb 2024 11:21:50 -0500 Subject: [PATCH] Don't check metadata for API docs by default (#817) Closes https://github.com/Qiskit/documentation/issues/793. This unblocks us starting to check API docs in https://github.com/Qiskit/documentation/issues/66. It also speeds up the workflow for non-API docs, which is valuable because non-API and API docs have such different workflows. I only added an `--apis` argument rather than e.g. `--current-apis` vs `--historical-apis` because this check is fast enough to not need the nuance. --------- Co-authored-by: Arnau Casau <47946624+arnaucasau@users.noreply.github.com> --- README.md | 10 +++-- scripts/commands/checkMetadata.ts | 74 ++++++++++++++++++++++--------- 2 files changed, 59 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 58dea483695..d55485049dd 100644 --- a/README.md +++ b/README.md @@ -157,14 +157,14 @@ npm run check:links npm run check:links -- --external # By default, only the non-API docs are checked. You can add any of the -# below arguments to also check API docs and/or Qiskit release notes. +# below arguments to also check API docs. npm run check:links -- --current-apis --dev-apis --historical-apis --qiskit-release-notes # However, `--historical-apis` currently has failing versions, so you may # want to add `--skip-broken-historical`. npm run check:links -- --historical-apis --skip-broken-historical -# Or, run all the checks +# Or, run all the checks. Although this only checks non-API docs. npm run check ``` @@ -178,7 +178,11 @@ You can also check for valid metadata locally: # Only check file metadata npm run check:metadata -# Or, run all the checks +# By default, only the non-API docs are checked. You can add any of the +# below arguments to also check API docs and/or translations. +npm run check:metadata -- --translations --apis + +# Or, run all the checks. Although this only checks non-API docs. npm run check ``` diff --git a/scripts/commands/checkMetadata.ts b/scripts/commands/checkMetadata.ts index f6e7a41b6ce..a5463c6af0f 100644 --- a/scripts/commands/checkMetadata.ts +++ b/scripts/commands/checkMetadata.ts @@ -10,14 +10,35 @@ // copyright notice, and modified files need to carry a notice indicating // that they have been altered from the originals. -import grayMatter from "gray-matter"; import fs from "fs/promises"; + +import yargs from "yargs/yargs"; +import { hideBin } from "yargs/helpers"; +import grayMatter from "gray-matter"; import { globby } from "globby"; -const IGNORED_FILES = new Set([ - "docs/api/qiskit/transpiler_builtin_plugins.md", - "docs/api/qiskit/dev/transpiler_builtin_plugins.md", -]); +interface Arguments { + [x: string]: unknown; + apis: boolean; + translations: boolean; +} + +const readArgs = (): Arguments => { + return yargs(hideBin(process.argv)) + .version(false) + .option("apis", { + type: "boolean", + default: false, + description: + "Check the API docs? Currently fails (https://github.com/Qiskit/documentation/issues/66)", + }) + .option("translations", { + type: "boolean", + default: false, + description: "Check the translations?", + }) + .parseSync(); +}; const readMetadata = async (filePath: string): Promise> => { const ext = filePath.split(".").pop(); @@ -36,18 +57,11 @@ const isValidMetadata = (metadata: Record): boolean => metadata.title && metadata.description; const main = async (): Promise => { + const args = readArgs(); + const [mdFiles, notebookFiles] = await determineFiles(args); + const mdErrors = []; - const mdFiles = await globby("docs/**/*.{md,mdx}"); for (const file of mdFiles) { - if (IGNORED_FILES.has(file)) { - continue; - } - - // Ignore all historical API version files. - if (/.*\/[0-9].*\//.test(file)) { - continue; - } - const metadata = await readMetadata(file); if (!isValidMetadata(metadata)) { mdErrors.push(file); @@ -55,17 +69,33 @@ const main = async (): Promise => { } const notebookErrors = []; - const notebookFiles = await globby("docs/**/*.ipynb"); for (const file of notebookFiles) { - if (IGNORED_FILES.has(file)) { - continue; - } const metadata = await readMetadata(file); if (!isValidMetadata(metadata)) { notebookErrors.push(file); } } + handleErrors(mdErrors, notebookErrors); +}; + +async function determineFiles(args: Arguments): Promise<[string[], string[]]> { + const mdGlobs = ["docs/**/*.{md,mdx}"]; + const notebookGlobs = ["docs/**/*.ipynb"]; + if (!args.apis) { + const apiIgnore = + "!docs/api/{qiskit,qiskit-ibm-provider,qiskit-ibm-runtime}/**/*"; + mdGlobs.push(apiIgnore); + notebookGlobs.push(apiIgnore); + } + if (args.translations) { + mdGlobs.push("translations/**/*.{md,mdx}"); + notebookGlobs.push("translations/**/*.ipynb"); + } + return [await globby(mdGlobs), await globby(notebookGlobs)]; +} + +function handleErrors(mdErrors: string[], notebookErrors: string[]): void { if (mdErrors.length > 0) { console.error(` Invalid markdown file metadata. Every .md and .mdx file should start with a metadata block like this: @@ -79,7 +109,7 @@ const main = async (): Promise => { in <160 characters, ideally using some keywords. The description is what shows up as the text in search results. See https://github.com/Qiskit/documentation/issues/131 for some tips. - Please fix these files: ${mdErrors} + Please fix these files:\n\n${mdErrors.join("\n")} `); } if (notebookErrors.length > 0) { @@ -113,12 +143,12 @@ const main = async (): Promise => { "kernelspec": { ... } - Please fix these files: ${notebookErrors} + Please fix these files:\n\n${notebookErrors.join("\n")} `); } if (mdErrors.length > 0 || notebookErrors.length > 0) { process.exit(1); } -}; +} main();