From 37f647e515fb1fb9703fa94784d3ef5450720a65 Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Wed, 15 May 2024 07:47:24 -0400
Subject: [PATCH] Allow manually created class pages (#1382)

This unblocks https://github.com/Qiskit/qiskit/pull/12403. Without this
PR, we incorrectly treat the class as inline, which means it gets the
blue left bar and an h3 incorrectly added.

Without this PR, our test to check that the ToC and index page are in
sync also fails, even though things behave how we expect
(https://github.com/Qiskit/qiskit/pull/12403#pullrequestreview-2056366501)
---
 scripts/lib/api/TocGrouping.test.ts      | 25 +++++++++++++++++-------
 scripts/lib/api/generateApiComponents.ts |  6 +++++-
 2 files changed, 23 insertions(+), 8 deletions(-)

diff --git a/scripts/lib/api/TocGrouping.test.ts b/scripts/lib/api/TocGrouping.test.ts
index b445b0d28fb..fccd3acdb44 100644
--- a/scripts/lib/api/TocGrouping.test.ts
+++ b/scripts/lib/api/TocGrouping.test.ts
@@ -82,16 +82,27 @@ async function getIndexModuleGroups(fp: string): Promise<ModuleGroup[]> {
   const result: ModuleGroup[] = [];
   let currentGroup: ModuleGroup = [];
   for (const line of rawIndex.split("\n")) {
-    if (line.startsWith("* ")) {
-      if (line.includes("qiskit.")) {
-        const module = extractModuleName(line);
-        currentGroup.push(module);
+    // Each ModuleGroup represents an unordered list of entries starting with `*`.
+    // So, when we stop encountering `*`, we need to start a new ModuleGroup.
+    if (!line.startsWith("* ")) {
+      if (currentGroup.length) {
+        result.push(currentGroup);
+        currentGroup = [];
       }
       continue;
-    } else if (currentGroup.length) {
-      result.push(currentGroup);
-      currentGroup = [];
     }
+
+    // Certain classes like QuantumCircuit in Qiskit 1.1+ have manually
+    // created pages. Those pages show up in index.mdx as top-level entries,
+    // but they are not top-level entries in the left ToC. This is expected.
+    // So, we allow the index to diverge from the left ToC.
+    //
+    // This is looking for e.g. '[`QuantumCircuit` class](qiskit.circuit.QuantumCircuit)'
+    const isDedicatedClassPage = line.includes(" class](");
+    if (isDedicatedClassPage) continue;
+
+    const module = extractModuleName(line);
+    currentGroup.push(module);
   }
   return result;
 }
diff --git a/scripts/lib/api/generateApiComponents.ts b/scripts/lib/api/generateApiComponents.ts
index 1d58ac1ead0..0aa1124be41 100644
--- a/scripts/lib/api/generateApiComponents.ts
+++ b/scripts/lib/api/generateApiComponents.ts
@@ -19,6 +19,7 @@ import remarkStringify from "remark-stringify";
 import { ApiType } from "./Metadata";
 import {
   getLastPartFromFullIdentifier,
+  removeSuffix,
   APOSTROPHE_HEX_CODE,
 } from "../stringUtils";
 
@@ -142,7 +143,10 @@ function prepareClassOrExceptionProps(
     modifiers,
   };
 
-  const pageHeading = $dl.siblings("h1").text();
+  let pageHeading = $dl.siblings("h1").text();
+  // Manually created class pages like Qiskit 1.1+'s `QuantumCircuit`
+  // sometimes have ' class' in their h1.
+  pageHeading = removeSuffix(pageHeading, " class");
   if (id.endsWith(pageHeading) && pageHeading != "") {
     // Page is already dedicated to the class
     return {