Group Qiskit table of contents into sections (#1255)

Closes #1211. See
Qiskit/qiskit#12333 for the sibling PR in
Qiskit. We'll land the test
#1300 once both PRs have
landed.

This uses the same grouping as
#1211 (comment),
if people prefer reviewing the list over code.

Before:
<img width="254" alt="Screenshot 2024-05-01 at 10 27 43 AM"
src="https://github.com/Qiskit/documentation/assets/14852634/5b503347-accd-4847-a7e2-aedf3546fcba">

After:

<img width="269" alt="Screenshot 2024-05-01 at 10 28 02 AM"
src="https://github.com/Qiskit/documentation/assets/14852634/c1a358f6-26f5-4e6e-80e9-2ee440eec94f">

<img width="272" alt="Screenshot 2024-05-01 at 10 28 15 AM"
src="https://github.com/Qiskit/documentation/assets/14852634/c3c80ca7-96e5-4942-ac39-6795b9504277">

This also improves historical APIs

<img width="271" alt="Screenshot 2024-05-01 at 10 29 08 AM"
src="https://github.com/Qiskit/documentation/assets/14852634/362cc70f-4c7e-49c4-9447-78af2a648452">

scripts/lib/api/Pkg.ts

@@ -15,7 +15,7 @@ import { join } from "path/posix";
 import { findSeparateReleaseNotesVersions } from "./releaseNotes";
 import { getRoot } from "../fs";
 import { determineHistoricalQiskitGithubUrl } from "../qiskitMetapackage";
-import { TocGrouping } from "./TocGrouping";
+import { TocGrouping, QISKIT_TOC_GROUPING } from "./TocGrouping";
 
 export class ReleaseNotesConfig {
   readonly enabled: boolean;
@@ -91,7 +91,7 @@ export class Pkg {
         releaseNotesConfig: new ReleaseNotesConfig({
           separatePagesVersions: releaseNoteEntries,
         }),
-        nestModulesInToc: true,
+        tocGrouping: QISKIT_TOC_GROUPING,
       });
     }
 

scripts/lib/api/TocGrouping.ts

@@ -10,6 +10,8 @@
 // copyright notice, and modified files need to carry a notice indicating
 // that they have been altered from the originals.
 
+import { hasPrefix } from "../stringUtils";
+
 /** A human-written section used to group several modules, e.g. 'Circuit Construction'. */
 type Section = {
   name: string;
@@ -38,3 +40,139 @@ export type TocGrouping = {
    * Return `undefined` if the module does not belong in any specific Section.*/
   moduleToSection: (module: string) => string | undefined;
 };
+
+// Qiskit section names
+const _CIRCUITS = "Circuit construction";
+const _TRANSPILATION = "Transpilation";
+const _PRIMITVES = "Primitives and providers";
+const _RESULTS = "Results and visualizations";
+const _OPFLOW = "Opflow";
+const _SERIALIZATION = "Serialization (OpenQASM and QPY)";
+const _PULSE = "Pulse-level programming";
+const _OTHER = "Other";
+const _AER = "Qiskit Aer";
+const _IBMQ = "IBM Q Provider";
+const _ALGORITHMS = "Algorithms";
+const _AQUA = "Qiskit Aqua";
+const _IGNIS = "Qiskit Ignis";
+const _FINANCE = "Finance";
+const _CHEMISTRY = "Chemistry";
+const _ML = "Machine learning";
+const _OPTIMIZATION = "Optimization";
+
+// The ordering of Qiskit ToC
+const QISKIT_ENTRIES = [
+  { moduleId: "qiskit", title: "API index", kind: "module" },
+  { name: _CIRCUITS, kind: "section" },
+  {
+    moduleId: "qiskit.quantum_info",
+    title: "Quantum information (qiskit.quantum_info)",
+    kind: "module",
+  },
+  { name: _TRANSPILATION, kind: "section" },
+  { name: _PRIMITVES, kind: "section" },
+  { name: _RESULTS, kind: "section" },
+  { name: _OPFLOW, kind: "section" },
+  { name: _SERIALIZATION, kind: "section" },
+  { name: _PULSE, kind: "section" },
+  { moduleId: "qiskit.execute", title: "qiskit.execute", kind: "module" },
+  {
+    moduleId: "qiskit.execute_function",
+    title: "qiskit.execute_function",
+    kind: "module",
+  },
+  { name: _OTHER, kind: "section" },
+  { name: _AER, kind: "section" },
+  { name: _IBMQ, kind: "section" },
+  { name: _ALGORITHMS, kind: "section" },
+  { name: _AQUA, kind: "section" },
+  { name: _IGNIS, kind: "section" },
+  { name: _FINANCE, kind: "section" },
+  { name: _CHEMISTRY, kind: "section" },
+  { name: _ML, kind: "section" },
+  { name: _OPTIMIZATION, kind: "section" },
+] as const;
+
+function qiskitModuleToSection(module: string): string | undefined {
+  if (
+    hasPrefix(module, ["qiskit.circuit", "qiskit.extensions"]) &&
+    module === "qiskit.circuit.qpy_serialization"
+  ) {
+    return _CIRCUITS;
+  }
+
+  if (
+    hasPrefix(module, [
+      "qiskit.converters",
+      "qiskit.dagcircuit",
+      "qiskit.passmanager",
+      "qiskit.synthesis",
+      "qiskit.synthesis",
+      "qiskit.transpiler",
+      "qiskit.transpiler.passes",
+    ])
+  ) {
+    return _TRANSPILATION;
+  }
+
+  if (
+    hasPrefix(module, ["qiskit.primitives", "qiskit.providers"]) &&
+    !hasPrefix(module, ["qiskit.providers.aer", "qiskit.providers.ibmq"])
+  ) {
+    return _PRIMITVES;
+  }
+
+  if (
+    hasPrefix(module, [
+      "qiskit.result",
+      "qiskit.validation",
+      "qiskit.visualization",
+    ])
+  ) {
+    return _RESULTS;
+  }
+
+  if (hasPrefix(module, ["qiskit.opflow"])) return _OPFLOW;
+
+  if (
+    hasPrefix(module, [
+      "qiskit.circuit.qpy_serialization",
+      "qiskit.qpy",
+      "qiskit.qasm",
+    ])
+  ) {
+    return _SERIALIZATION;
+  }
+
+  if (hasPrefix(module, ["qiskit.scheduler", "qiskit.pulse"])) return _PULSE;
+
+  if (
+    hasPrefix(module, [
+      "qiskit.assembler",
+      "qiskit.compiler",
+      "qiskit.exceptions",
+      "qiskit.qobj",
+      "qiskit.tools",
+      "qiskit.utils",
+    ])
+  ) {
+    return _OTHER;
+  }
+
+  if (hasPrefix(module, ["qiskit.providers.aer", "qiskit_aer"])) return _AER;
+  if (hasPrefix(module, ["qiskit.providers.ibmq"])) return _IBMQ;
+  if (hasPrefix(module, ["qiskit.algorithms"])) return _ALGORITHMS;
+  if (hasPrefix(module, ["qiskit.aqua"])) return _AQUA;
+  if (hasPrefix(module, ["qiskit.ignis"])) return _IGNIS;
+  if (hasPrefix(module, ["qiskit.finance"])) return _FINANCE;
+  if (hasPrefix(module, ["qiskit.chemistry"])) return _CHEMISTRY;
+  if (hasPrefix(module, ["qiskit.ml"])) return _ML;
+  if (hasPrefix(module, ["qiskit.optimization"])) return _OPTIMIZATION;
+
+  return undefined;
+}
+
+export const QISKIT_TOC_GROUPING: TocGrouping = {
+  entries: QISKIT_ENTRIES,
+  moduleToSection: qiskitModuleToSection,
+};