From 373e214c183ac22e70eacaab11788d07e5d15b2e Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Wed, 1 May 2024 08:49:05 -0400
Subject: [PATCH 01/17] Add index page to left ToC for Runtime and Provider

---
 scripts/commands/checkOrphanPages.ts          |  3 ---
 .../conversionPipeline.test.ts.snap           |  4 ++++
 scripts/lib/api/generateToc.test.ts           | 12 ++++++++--
 scripts/lib/api/generateToc.ts                | 23 +++++++++++++++++++
 4 files changed, 37 insertions(+), 5 deletions(-)

diff --git a/scripts/commands/checkOrphanPages.ts b/scripts/commands/checkOrphanPages.ts
index edd76800ad3..17cfb191fa5 100644
--- a/scripts/commands/checkOrphanPages.ts
+++ b/scripts/commands/checkOrphanPages.ts
@@ -179,8 +179,6 @@ function apiDocsIgnores(): string[] {
 
   return [
     ...versions.flatMap((vers) => [
-      `/api/qiskit-ibm-runtime/${vers}index`,
-      `/api/qiskit-ibm-provider/${vers}index`,
       `/api/qiskit-ibm-runtime/${vers}qiskit_ibm_runtime.Estimator`,
       `/api/qiskit-ibm-runtime/${vers}qiskit_ibm_runtime.Sampler`,
       `/api/qiskit/${vers}aer`,
@@ -195,7 +193,6 @@ function apiDocsIgnores(): string[] {
       `/api/qiskit/${vers}parallel`,
       `/api/qiskit/${vers}transpiler_builtin_plugins`,
     ]),
-    `/api/qiskit/0.19/index`,
     `/api/qiskit/dev/qiskit.primitives.BaseEstimator`,
     `/api/qiskit/dev/qiskit.primitives.BaseSampler`,
   ];
diff --git a/scripts/lib/api/__snapshots__/conversionPipeline.test.ts.snap b/scripts/lib/api/__snapshots__/conversionPipeline.test.ts.snap
index d68823ba295..8fdbf0e05e4 100644
--- a/scripts/lib/api/__snapshots__/conversionPipeline.test.ts.snap
+++ b/scripts/lib/api/__snapshots__/conversionPipeline.test.ts.snap
@@ -12,6 +12,10 @@ exports[`qiskit-sphinx-theme: _toc 1`] = `
 "{
   "title": "Qiskit Sphinx Theme",
   "children": [
+    {
+      "title": "API index",
+      "url": "/api/qiskit-sphinx-theme"
+    },
     {
       "title": "api_example",
       "children": [
diff --git a/scripts/lib/api/generateToc.test.ts b/scripts/lib/api/generateToc.test.ts
index b706b52f4eb..9d84f0d44ba 100644
--- a/scripts/lib/api/generateToc.test.ts
+++ b/scripts/lib/api/generateToc.test.ts
@@ -179,7 +179,11 @@ describe("generateToc", () => {
   test("TOC with grouped modules", () => {
     // This ordering is intentional.
     const topLevelEntries: TocGroupingEntry[] = [
-      { moduleId: "my_quantum_project", title: "API index", kind: "module" },
+      {
+        moduleId: "my_quantum_project",
+        title: "API index (custom)",
+        kind: "module",
+      },
       { name: "Group 2", kind: "section" },
       { name: "Group 1", kind: "section" },
       {
@@ -236,7 +240,7 @@ describe("generateToc", () => {
       title: "My Quantum Project",
       children: [
         {
-          title: "API index",
+          title: "API index (custom)",
           url: "/api/my-quantum-project",
         },
         {
@@ -354,6 +358,10 @@ describe("generateToc", () => {
 
     expect(toc).toEqual({
       children: [
+        {
+          title: "API index",
+          url: "/api/my-quantum-project",
+        },
         {
           title: "Release notes",
           url: "/api/my-quantum-project/release-notes",
diff --git a/scripts/lib/api/generateToc.ts b/scripts/lib/api/generateToc.ts
index d899d9620cc..d67929e3c7d 100644
--- a/scripts/lib/api/generateToc.ts
+++ b/scripts/lib/api/generateToc.ts
@@ -59,6 +59,10 @@ export function generateToc(pkg: Pkg, results: HtmlToMdResultWithUrl[]): Toc {
   }
 
   generateOverviewPage(tocModules);
+  const maybeIndexPage = ensureIndexPage(pkg, sortedTocModules);
+  if (maybeIndexPage) {
+    sortedTocModules.unshift(maybeIndexPage);
+  }
 
   return {
     title: pkg.title,
@@ -231,6 +235,25 @@ function sortAndTruncateModules(entries: TocEntry[]): TocEntry[] {
   return sorted;
 }
 
+/**
+ * Create a new TocEntry pointing to the index page if is not already there.
+ *
+ * Certain APIs like Runtime and Provider do not have the index page included,
+ * whereas Qiskit SDK already does.
+ */
+function ensureIndexPage(
+  pkg: Pkg,
+  tocModules: TocEntry[],
+): TocEntry | undefined {
+  const docsFolder = pkg.outputDir("/");
+  return tocModules.some((entry) => entry.url === docsFolder)
+    ? undefined
+    : {
+        title: "API index",
+        url: docsFolder,
+      };
+}
+
 function generateOverviewPage(tocModules: TocEntry[]): void {
   for (const tocModule of tocModules) {
     if (tocModule.children && tocModule.children.length > 0) {

From e3c1bed6445e963dab673ddcff40da9769eadab3 Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Wed, 1 May 2024 08:49:42 -0400
Subject: [PATCH 02/17] Regenerate qiskit-ibm-runtime 0.14.0

---
 docs/api/qiskit-ibm-runtime/0.14/_toc.json | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/api/qiskit-ibm-runtime/0.14/_toc.json b/docs/api/qiskit-ibm-runtime/0.14/_toc.json
index eab2a1c1c76..7c179206d63 100644
--- a/docs/api/qiskit-ibm-runtime/0.14/_toc.json
+++ b/docs/api/qiskit-ibm-runtime/0.14/_toc.json
@@ -1,6 +1,10 @@
 {
   "title": "Qiskit Runtime IBM Client",
   "children": [
+    {
+      "title": "API index",
+      "url": "/api/qiskit-ibm-runtime/0.14"
+    },
     {
       "title": "qiskit_ibm_runtime",
       "children": [

From f1f557eeffc9d5ecee5f48eb2186cf2fad73c9b4 Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Wed, 1 May 2024 08:49:44 -0400
Subject: [PATCH 03/17] Regenerate qiskit-ibm-runtime 0.15.0

---
 docs/api/qiskit-ibm-runtime/0.15/_toc.json | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/api/qiskit-ibm-runtime/0.15/_toc.json b/docs/api/qiskit-ibm-runtime/0.15/_toc.json
index 745e6ef91fd..b4212e8c2f4 100644
--- a/docs/api/qiskit-ibm-runtime/0.15/_toc.json
+++ b/docs/api/qiskit-ibm-runtime/0.15/_toc.json
@@ -1,6 +1,10 @@
 {
   "title": "Qiskit Runtime IBM Client",
   "children": [
+    {
+      "title": "API index",
+      "url": "/api/qiskit-ibm-runtime/0.15"
+    },
     {
       "title": "qiskit_ibm_runtime",
       "children": [

From 528d4aa9f96c73f8fc257e821daf30a03decdfd8 Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Wed, 1 May 2024 08:49:47 -0400
Subject: [PATCH 04/17] Regenerate qiskit-ibm-runtime 0.16.1

---
 docs/api/qiskit-ibm-runtime/0.16/_toc.json | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/api/qiskit-ibm-runtime/0.16/_toc.json b/docs/api/qiskit-ibm-runtime/0.16/_toc.json
index 3381aa3b34e..742c9e1a081 100644
--- a/docs/api/qiskit-ibm-runtime/0.16/_toc.json
+++ b/docs/api/qiskit-ibm-runtime/0.16/_toc.json
@@ -1,6 +1,10 @@
 {
   "title": "Qiskit Runtime IBM Client",
   "children": [
+    {
+      "title": "API index",
+      "url": "/api/qiskit-ibm-runtime/0.16"
+    },
     {
       "title": "qiskit_ibm_runtime",
       "children": [

From 9809ab85a0b1b541f8e8d185c0187712808173fe Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Wed, 1 May 2024 08:49:49 -0400
Subject: [PATCH 05/17] Regenerate qiskit-ibm-runtime 0.17.0

---
 docs/api/qiskit-ibm-runtime/0.17/_toc.json | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/api/qiskit-ibm-runtime/0.17/_toc.json b/docs/api/qiskit-ibm-runtime/0.17/_toc.json
index 5a187a54354..bfe97f819a0 100644
--- a/docs/api/qiskit-ibm-runtime/0.17/_toc.json
+++ b/docs/api/qiskit-ibm-runtime/0.17/_toc.json
@@ -1,6 +1,10 @@
 {
   "title": "Qiskit Runtime IBM Client",
   "children": [
+    {
+      "title": "API index",
+      "url": "/api/qiskit-ibm-runtime/0.17"
+    },
     {
       "title": "qiskit_ibm_runtime",
       "children": [

From 18308734587d24e259c168b7f3525db26a2aa188 Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Wed, 1 May 2024 08:49:55 -0400
Subject: [PATCH 06/17] Regenerate qiskit-ibm-runtime 0.18.0

---
 docs/api/qiskit-ibm-runtime/0.18/_toc.json | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/api/qiskit-ibm-runtime/0.18/_toc.json b/docs/api/qiskit-ibm-runtime/0.18/_toc.json
index 53a11e23a65..378fc78eeb7 100644
--- a/docs/api/qiskit-ibm-runtime/0.18/_toc.json
+++ b/docs/api/qiskit-ibm-runtime/0.18/_toc.json
@@ -1,6 +1,10 @@
 {
   "title": "Qiskit Runtime IBM Client",
   "children": [
+    {
+      "title": "API index",
+      "url": "/api/qiskit-ibm-runtime/0.18"
+    },
     {
       "title": "qiskit_ibm_runtime",
       "children": [

From be4c4bbfc7bfdaf6b8843b1b7d0857f381bc4f8f Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Wed, 1 May 2024 08:50:02 -0400
Subject: [PATCH 07/17] Regenerate qiskit-ibm-runtime 0.19.1

---
 docs/api/qiskit-ibm-runtime/0.19/_toc.json | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/api/qiskit-ibm-runtime/0.19/_toc.json b/docs/api/qiskit-ibm-runtime/0.19/_toc.json
index dacc1714ed2..cc71b82bb76 100644
--- a/docs/api/qiskit-ibm-runtime/0.19/_toc.json
+++ b/docs/api/qiskit-ibm-runtime/0.19/_toc.json
@@ -1,6 +1,10 @@
 {
   "title": "Qiskit Runtime IBM Client",
   "children": [
+    {
+      "title": "API index",
+      "url": "/api/qiskit-ibm-runtime/0.19"
+    },
     {
       "title": "qiskit_ibm_runtime",
       "children": [

From c6a351b5afd902b04e43bd9e62ed6adc7bac172c Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Wed, 1 May 2024 08:50:08 -0400
Subject: [PATCH 08/17] Regenerate qiskit-ibm-runtime 0.20.0

---
 docs/api/qiskit-ibm-runtime/0.20/_toc.json | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/api/qiskit-ibm-runtime/0.20/_toc.json b/docs/api/qiskit-ibm-runtime/0.20/_toc.json
index 564e1d15126..d3941dd769d 100644
--- a/docs/api/qiskit-ibm-runtime/0.20/_toc.json
+++ b/docs/api/qiskit-ibm-runtime/0.20/_toc.json
@@ -1,6 +1,10 @@
 {
   "title": "Qiskit Runtime IBM Client",
   "children": [
+    {
+      "title": "API index",
+      "url": "/api/qiskit-ibm-runtime/0.20"
+    },
     {
       "title": "qiskit_ibm_runtime",
       "children": [

From a47cfcb32e58461d2fd4ed489e8a37ea6da607c2 Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Wed, 1 May 2024 08:50:15 -0400
Subject: [PATCH 09/17] Regenerate qiskit-ibm-runtime 0.21.1

---
 docs/api/qiskit-ibm-runtime/0.21/_toc.json | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/api/qiskit-ibm-runtime/0.21/_toc.json b/docs/api/qiskit-ibm-runtime/0.21/_toc.json
index 481e2de8785..4f5491f187c 100644
--- a/docs/api/qiskit-ibm-runtime/0.21/_toc.json
+++ b/docs/api/qiskit-ibm-runtime/0.21/_toc.json
@@ -1,6 +1,10 @@
 {
   "title": "Qiskit Runtime IBM Client",
   "children": [
+    {
+      "title": "API index",
+      "url": "/api/qiskit-ibm-runtime/0.21"
+    },
     {
       "title": "qiskit_ibm_runtime",
       "children": [

From 6c222de1b873153aa6bf02df24d75fb7cb73310d Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Wed, 1 May 2024 08:50:23 -0400
Subject: [PATCH 10/17] Regenerate qiskit-ibm-runtime 0.22.0

---
 docs/api/qiskit-ibm-runtime/0.22/_toc.json | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/api/qiskit-ibm-runtime/0.22/_toc.json b/docs/api/qiskit-ibm-runtime/0.22/_toc.json
index 5dd542d276f..3a8b2e6d257 100644
--- a/docs/api/qiskit-ibm-runtime/0.22/_toc.json
+++ b/docs/api/qiskit-ibm-runtime/0.22/_toc.json
@@ -1,6 +1,10 @@
 {
   "title": "Qiskit Runtime IBM Client",
   "children": [
+    {
+      "title": "API index",
+      "url": "/api/qiskit-ibm-runtime/0.22"
+    },
     {
       "title": "qiskit_ibm_runtime",
       "children": [

From c878bad3c9bd1b51fb97338deae8a90ca89b8716 Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Wed, 1 May 2024 08:50:31 -0400
Subject: [PATCH 11/17] Regenerate qiskit-ibm-runtime 0.23.0

---
 docs/api/qiskit-ibm-runtime/_toc.json | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/api/qiskit-ibm-runtime/_toc.json b/docs/api/qiskit-ibm-runtime/_toc.json
index e3720673ca4..26f218779c1 100644
--- a/docs/api/qiskit-ibm-runtime/_toc.json
+++ b/docs/api/qiskit-ibm-runtime/_toc.json
@@ -1,6 +1,10 @@
 {
   "title": "Qiskit Runtime IBM Client",
   "children": [
+    {
+      "title": "API index",
+      "url": "/api/qiskit-ibm-runtime"
+    },
     {
       "title": "qiskit_ibm_runtime",
       "children": [

From 7b1af47e7f98c04067e5e4a345c5ef040e9f3eb9 Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Wed, 1 May 2024 08:50:38 -0400
Subject: [PATCH 12/17] Regenerate qiskit-ibm-runtime 0.24.0-dev

---
 docs/api/qiskit-ibm-runtime/dev/_toc.json | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/api/qiskit-ibm-runtime/dev/_toc.json b/docs/api/qiskit-ibm-runtime/dev/_toc.json
index b9fda71c3a8..d537051266d 100644
--- a/docs/api/qiskit-ibm-runtime/dev/_toc.json
+++ b/docs/api/qiskit-ibm-runtime/dev/_toc.json
@@ -1,6 +1,10 @@
 {
   "title": "Qiskit Runtime IBM Client",
   "children": [
+    {
+      "title": "API index",
+      "url": "/api/qiskit-ibm-runtime/dev"
+    },
     {
       "title": "qiskit_ibm_runtime",
       "children": [

From db94efd2c3b51f97ddeb2945f51acd109ab68201 Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Wed, 1 May 2024 08:51:02 -0400
Subject: [PATCH 13/17] Regenerate qiskit-ibm-provider 0.10.0

---
 docs/api/qiskit-ibm-provider/0.10/_toc.json | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/api/qiskit-ibm-provider/0.10/_toc.json b/docs/api/qiskit-ibm-provider/0.10/_toc.json
index 2137d7500e0..fcc0ba6749a 100644
--- a/docs/api/qiskit-ibm-provider/0.10/_toc.json
+++ b/docs/api/qiskit-ibm-provider/0.10/_toc.json
@@ -1,6 +1,10 @@
 {
   "title": "Qiskit IBM Provider (deprecated)",
   "children": [
+    {
+      "title": "API index",
+      "url": "/api/qiskit-ibm-provider/0.10"
+    },
     {
       "title": "qiskit_ibm_provider",
       "children": [

From a3565f22529d7b1bc2e361ea324b579a218b6213 Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Wed, 1 May 2024 08:51:05 -0400
Subject: [PATCH 14/17] Regenerate qiskit-ibm-provider 0.7.3

---
 docs/api/qiskit-ibm-provider/0.7/_toc.json | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/api/qiskit-ibm-provider/0.7/_toc.json b/docs/api/qiskit-ibm-provider/0.7/_toc.json
index 1643ed247a6..82c34cff016 100644
--- a/docs/api/qiskit-ibm-provider/0.7/_toc.json
+++ b/docs/api/qiskit-ibm-provider/0.7/_toc.json
@@ -1,6 +1,10 @@
 {
   "title": "Qiskit IBM Provider (deprecated)",
   "children": [
+    {
+      "title": "API index",
+      "url": "/api/qiskit-ibm-provider/0.7"
+    },
     {
       "title": "qiskit_ibm_provider",
       "children": [

From c5ba19515d29fe8e3539f755064a0393eedb3348 Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Wed, 1 May 2024 08:51:08 -0400
Subject: [PATCH 15/17] Regenerate qiskit-ibm-provider 0.8.0

---
 docs/api/qiskit-ibm-provider/0.8/_toc.json | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/api/qiskit-ibm-provider/0.8/_toc.json b/docs/api/qiskit-ibm-provider/0.8/_toc.json
index 83a0aec95f8..41159332a3a 100644
--- a/docs/api/qiskit-ibm-provider/0.8/_toc.json
+++ b/docs/api/qiskit-ibm-provider/0.8/_toc.json
@@ -1,6 +1,10 @@
 {
   "title": "Qiskit IBM Provider (deprecated)",
   "children": [
+    {
+      "title": "API index",
+      "url": "/api/qiskit-ibm-provider/0.8"
+    },
     {
       "title": "qiskit_ibm_provider",
       "children": [

From 724dff67f25cff74f3d14d001af060ada0ce3c0c Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Wed, 1 May 2024 08:51:10 -0400
Subject: [PATCH 16/17] Regenerate qiskit-ibm-provider 0.9.0

---
 docs/api/qiskit-ibm-provider/0.9/_toc.json | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/api/qiskit-ibm-provider/0.9/_toc.json b/docs/api/qiskit-ibm-provider/0.9/_toc.json
index 7b4ef18e635..fb561523379 100644
--- a/docs/api/qiskit-ibm-provider/0.9/_toc.json
+++ b/docs/api/qiskit-ibm-provider/0.9/_toc.json
@@ -1,6 +1,10 @@
 {
   "title": "Qiskit IBM Provider (deprecated)",
   "children": [
+    {
+      "title": "API index",
+      "url": "/api/qiskit-ibm-provider/0.9"
+    },
     {
       "title": "qiskit_ibm_provider",
       "children": [

From 4deeee9b4efaa21256bfe9317991611abad4c0ca Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Wed, 1 May 2024 08:51:13 -0400
Subject: [PATCH 17/17] Regenerate qiskit-ibm-provider 0.11.0

---
 docs/api/qiskit-ibm-provider/_toc.json | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/api/qiskit-ibm-provider/_toc.json b/docs/api/qiskit-ibm-provider/_toc.json
index c86fb3541bb..2062491bbdf 100644
--- a/docs/api/qiskit-ibm-provider/_toc.json
+++ b/docs/api/qiskit-ibm-provider/_toc.json
@@ -1,6 +1,10 @@
 {
   "title": "Qiskit IBM Provider (deprecated)",
   "children": [
+    {
+      "title": "API index",
+      "url": "/api/qiskit-ibm-provider"
+    },
     {
       "title": "qiskit_ibm_provider",
       "children": [