Don't check metadata for API docs by default (#817)

Closes #793. 

This unblocks us starting to check API docs in
#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

@@ -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
 ```
 

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<Record<string, any>> => {
   const ext = filePath.split(".").pop();
@@ -36,36 +57,45 @@ const isValidMetadata = (metadata: Record<string, any>): boolean =>
   metadata.title && metadata.description;
 
 const main = async (): Promise<void> => {
+  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);
     }
   }
 
   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<void> => {
       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<void> => {
         "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();