Add more tests for API generation script

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[],