Add more tests for API generation script (Qiskit#581)

Part of Qiskit#223. 

One way to improve the maintainability of our API generation is to test
more. It gives us confidence we aren't breaking things and it makes it
more obvious how the function behaves.

This PR also makes some light refactoring like renaming things to be
more clear.

---------

Co-authored-by: Arnau Casau <[email protected]>
Co-authored-by: Arnau Casau <[email protected]>

docs/api/qiskit-ibm-provider/index.md

@@ -1,8 +1,6 @@
 ---
-
 title: Qiskit IBM Provider API Docs
 description: API documentation for qiskit-ibm-provider
-
 ---
 
 # qiskit-ibm-provider API Reference

docs/api/qiskit-ibm-runtime/0.14/index.md

@@ -1,8 +1,6 @@
 ---
-
 title: Qiskit Runtime IBM Client API Docs
 description: API documentation for qiskit-ibm-runtime
-
 ---
 
 # qiskit-ibm-runtime API reference

docs/api/qiskit-ibm-runtime/0.15/index.md

@@ -1,8 +1,6 @@
 ---
-
 title: Qiskit Runtime IBM Client API Docs
 description: API documentation for qiskit-ibm-runtime
-
 ---
 
 # qiskit-ibm-runtime API reference

docs/api/qiskit-ibm-runtime/0.16/index.md

@@ -1,8 +1,6 @@
 ---
-
 title: Qiskit Runtime IBM Client API Docs
 description: API documentation for qiskit-ibm-runtime
-
 ---
 
 # qiskit-ibm-runtime API reference

docs/api/qiskit-ibm-runtime/index.md

@@ -1,8 +1,6 @@
 ---
-
 title: Qiskit Runtime IBM Client API Docs
 description: API documentation for qiskit-ibm-runtime
-
 ---
 
 # qiskit-ibm-runtime API reference

docs/api/qiskit/release-notes/0.45.md

@@ -1,6 +1,6 @@
 ---
 title: Qiskit 0.45 release notes
-description: Changes made to Qiskit
+description: Changes made in Qiskit 0.45
 in_page_toc_max_heading_level: 2
 ---
 

scripts/commands/updateApiDocs.ts

@@ -23,17 +23,17 @@ import { saveImages } from "../lib/saveImages";
 import { generateToc } from "../lib/sphinx/generateToc";
 import { SphinxToMdResult } from "../lib/sphinx/SphinxToMdResult";
 import { mergeClassMembers } from "../lib/sphinx/mergeClassMembers";
-import { flatFolders } from "../lib/sphinx/flatFolders";
+import flattenFolders from "../lib/sphinx/flattenFolders";
 import { updateLinks } from "../lib/sphinx/updateLinks";
-import specialCaseResults from "../lib/sphinx/specialCaseResults";
-import { addFrontMatter } from "../lib/sphinx/addFrontMatter";
-import { dedupeResultIds } from "../lib/sphinx/dedupeIds";
+import { specialCaseResults } from "../lib/sphinx/specialCaseResults";
+import addFrontMatter from "../lib/sphinx/addFrontMatter";
+import { dedupeHtmlIdsFromResults } from "../lib/sphinx/dedupeHtmlIds";
 import { removePrefix, removeSuffix } from "../lib/stringUtils";
 import yargs from "yargs/yargs";
 import { hideBin } from "yargs/helpers";
 import { Pkg, PkgInfo, Link } from "../lib/sharedTypes";
 import transformLinks from "transform-markdown-links";
-import { downloadCIArtifact } from "../lib/downloadArtifacts";
+import { downloadCIArtifact } from "../lib/downloadCIArtifacts";
 import {
   findLegacyReleaseNotes,
   addNewReleaseNotes,
@@ -272,10 +272,10 @@ async function convertHtmlToMarkdown(
   }
 
   results = await mergeClassMembers(results);
-  flatFolders(results);
+  flattenFolders(results);
   specialCaseResults(results);
   await updateLinks(results, pkg.transformLink);
-  await dedupeResultIds(results);
+  await dedupeHtmlIdsFromResults(results);
   addFrontMatter(results, pkg);
 
   for (const result of results) {

scripts/lib/downloadArtifacts.test.ts → scripts/lib/downloadCIArtifacts.test.ts

@@ -11,9 +11,10 @@
 // that they have been altered from the originals.
 
 import { describe, expect, test } from "@jest/globals";
-import { getArtifactID } from "./downloadArtifacts";
 
-describe("downloadArtifacts", () => {
+import { getArtifactID } from "./downloadCIArtifacts";
+
+describe("getArtifactID()", () => {
   test("Pass the full URL of the artifact", () => {
     const artifactID = getArtifactID(
       "https://github.com/Qiskit/qiskit/suites/17881600359/artifacts/1026798160",

scripts/lib/downloadArtifacts.ts → scripts/lib/downloadCIArtifacts.ts

@@ -11,7 +11,7 @@
 // that they have been altered from the originals.
 
 import { $ } from "zx";
-import { pathExists, getRoot } from "../lib/fs";
+import { pathExists, getRoot } from "./fs";
 import { mkdirp } from "mkdirp";
 
 export function getArtifactID(url: string) {

scripts/lib/fs.test.ts

@@ -0,0 +1,26 @@
+// 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.
+
+import { expect, test } from "@jest/globals";
+
+import { getRoot, pathExists } from "./fs";
+
+test("pathExists() with getRoot()", async () => {
+  const readme = await pathExists(`${getRoot()}/README.md`);
+  expect(readme).toBe(true);
+
+  const dir = await pathExists(`${getRoot()}/docs/`);
+  expect(dir).toBe(true);
+
+  const fake = await pathExists(`${getRoot()}/fake-file`);
+  expect(fake).toBe(false);
+});

scripts/lib/sphinx/addFrontMatter.test.ts

@@ -0,0 +1,97 @@
+// 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.
+
+import { expect, test } from "@jest/globals";
+
+import addFrontMatter from "./addFrontMatter";
+import { Pkg } from "../sharedTypes";
+import { SphinxToMdResult } from "./SphinxToMdResult";
+
+test("addFrontMatter()", () => {
+  const results: SphinxToMdResult[] = [
+    {
+      markdown: "# Hardcoded!",
+      meta: {
+        hardcoded_frontmatter: "title: hardcoded\ndescription: Hello world!",
+      },
+      images: [],
+      isReleaseNotes: false,
+    },
+    {
+      markdown: "# Hardcoded with python_api_name!",
+      meta: {
+        hardcoded_frontmatter:
+          "title: hardcoded with python_api_name\ndescription: Hello world!",
+        python_api_name: "quantum_software.MyClass",
+        python_api_type: "class",
+      },
+      images: [],
+      isReleaseNotes: true,
+    },
+    {
+      markdown: "# Python API",
+      meta: {
+        python_api_name: "quantum_software.MyClass",
+        python_api_type: "class",
+      },
+      images: [],
+      isReleaseNotes: false,
+    },
+    {
+      markdown: "# Some release notes!",
+      meta: {},
+      images: [],
+      isReleaseNotes: true,
+    },
+  ];
+  const pkg = {
+    versionWithoutPatch: "0.0",
+    hasSeparateReleaseNotes: true,
+    title: "My Quantum Software Project",
+  } as Pkg;
+
+  addFrontMatter(results, pkg);
+  expect(results.map((result) => result.markdown)).toEqual([
+    `---
+title: hardcoded
+description: Hello world!
+---
+
+# Hardcoded!
+`,
+    `---
+title: hardcoded with python_api_name
+description: Hello world!
+---
+
+# Hardcoded with python_api_name!
+`,
+    `---
+title: MyClass
+description: API reference for quantum_software.MyClass
+in_page_toc_min_heading_level: 1
+python_api_type: class
+python_api_name: quantum_software.MyClass
+---
+
+# Python API
+`,
+    `---
+title: My Quantum Software Project 0.0 release notes
+description: Changes made in My Quantum Software Project 0.0
+in_page_toc_max_heading_level: 2
+---
+
+# Some release notes!
+`,
+  ]);
+});

scripts/lib/sphinx/addFrontMatter.ts

@@ -14,7 +14,7 @@ import { getLastPartFromFullIdentifier } from "../stringUtils";
 import { SphinxToMdResult } from "./SphinxToMdResult";
 import { Pkg } from "../sharedTypes";
 
-export function addFrontMatter<T extends SphinxToMdResult>(
+function addFrontMatter<T extends SphinxToMdResult>(
   results: T[],
   pkg: Pkg,
 ): void {
@@ -39,11 +39,15 @@ python_api_name: ${result.meta.python_api_name}
 ${markdown}
 `;
     } else if (result.isReleaseNotes) {
+      const versionStr = pkg.hasSeparateReleaseNotes
+        ? ` ${pkg.versionWithoutPatch}`
+        : "";
+      const descriptionSuffix = pkg.hasSeparateReleaseNotes
+        ? `in ${pkg.title}${versionStr}`
+        : `to ${pkg.title}`;
       result.markdown = `---
-title: ${pkg.title}${
-        pkg.hasSeparateReleaseNotes ? " " + pkg.versionWithoutPatch : ""
-      } release notes
-description: Changes made to ${pkg.title}
+title: ${pkg.title}${versionStr} release notes
+description: Changes made ${descriptionSuffix}
 in_page_toc_max_heading_level: 2
 ---
 
@@ -52,3 +56,5 @@ ${markdown}
     }
   }
 }
+
+export default addFrontMatter;

scripts/lib/sphinx/dedupeIds.test.ts → scripts/lib/sphinx/dedupeHtmlIds.test.ts

@@ -10,23 +10,22 @@
 // copyright notice, and modified files need to carry a notice indicating
 // that they have been altered from the originals.
 
-import { describe, expect, test } from "@jest/globals";
-import { dedupeIds } from "./dedupeIds";
+import { expect, test } from "@jest/globals";
 
-describe("dedupeIds", () => {
-  test("dedupeIds", async () => {
-    expect(
-      await dedupeIds(`
-    <span id="foo" />
-    <span id="bar" />
-    # foo
-    <span id="foo" />
-    `),
-    ).toMatchInlineSnapshot(`
-      "<span id="bar" />
+import { dedupeHtmlIds } from "./dedupeHtmlIds";
+
+test("dedupeHtmlIds()", async () => {
+  expect(
+    await dedupeHtmlIds(`
+  <span id="foo" />
+  <span id="bar" />
+  # foo
+  <span id="foo" />
+  `),
+  ).toMatchInlineSnapshot(`
+    "<span id="bar" />
 
-      # foo
-      "
-    `);
-  });
+    # foo
+    "
+  `);
 });

scripts/lib/sphinx/dedupeIds.ts → scripts/lib/sphinx/dedupeHtmlIds.ts

@@ -18,20 +18,20 @@ import remarkMdx from "remark-mdx";
 import { Root } from "mdast";
 import { visit } from "unist-util-visit";
 import remarkStringify from "remark-stringify";
-import { remarkStringifyOptions } from "./unifiedParser";
+import { remarkStringifyOptions } from "./commonParserConfig";
 import { toText } from "hast-util-to-text";
 import Slugger from "github-slugger";
 import { SphinxToMdResult } from "./SphinxToMdResult";
 
-export async function dedupeResultIds(
+export async function dedupeHtmlIdsFromResults(
   results: SphinxToMdResult[],
 ): Promise<void> {
   for (let result of results) {
-    result.markdown = await dedupeIds(result.markdown);
+    result.markdown = await dedupeHtmlIds(result.markdown);
   }
 }
 
-export async function dedupeIds(md: string): Promise<string> {
+export async function dedupeHtmlIds(md: string): Promise<string> {
   const output = await unified()
     .use(remarkParse)
     .use(remarkMath)

scripts/lib/sphinx/flattenFolders.test.ts

@@ -0,0 +1,33 @@
+// 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.
+
+import { expect, test } from "@jest/globals";
+
+import flattenFolders from "./flattenFolders";
+import { SphinxToMdResultWithUrl } from "./SphinxToMdResult";
+
+test("flattenFolders()", () => {
+  const results = [
+    { url: "/api/my-pkg/apidoc/my_module" },
+    { url: "/api/my-pkg/apidocs/my_module2" },
+    { url: "/api/my-pkg/stubs/my_module.foo.Bar" },
+    { url: "/api/my-pkg/release_notes" },
+  ] as SphinxToMdResultWithUrl[];
+
+  flattenFolders(results);
+  expect(results.map((result) => result.url)).toEqual([
+    "/api/my-pkg/my_module",
+    "/api/my-pkg/my_module2",
+    "/api/my-pkg/my_module.foo.Bar",
+    "/api/my-pkg/release_notes",
+  ]);
+});

scripts/lib/sphinx/flatFolders.ts → scripts/lib/sphinx/flattenFolders.ts

@@ -13,7 +13,7 @@
 import { SphinxToMdResultWithUrl } from "./SphinxToMdResult";
 import { removePart } from "../stringUtils";
 
-export function flatFolders(results: SphinxToMdResultWithUrl[]): void {
+function flattenFolders(results: SphinxToMdResultWithUrl[]): void {
   for (const result of results) {
     result.url = omitRootFolders(result.url);
   }
@@ -22,3 +22,5 @@ export function flatFolders(results: SphinxToMdResultWithUrl[]): void {
 function omitRootFolders(path: string): string {
   return removePart(path, "/", ["stubs", "apidocs", "apidoc"]);
 }
+
+export default flattenFolders;

scripts/lib/sphinx/mergeClassMembers.ts

@@ -20,7 +20,7 @@ import remarkStringify from "remark-stringify";
 import { Content, Root } from "mdast";
 import { visit } from "unist-util-visit";
 import { SphinxToMdResultWithUrl } from "./SphinxToMdResult";
-import { remarkStringifyOptions } from "./unifiedParser";
+import { remarkStringifyOptions } from "./commonParserConfig";
 
 export async function mergeClassMembers<T extends SphinxToMdResultWithUrl>(
   results: T[],