Add index page to left ToC for Runtime and Provider (Qiskit#1269)

Closes Qiskit#1249. Some of the reasons we decided to make this change: 1. Consistency with Qiskit SDK 2. It's useful to show the currently selected page in the left ToC when you land on the index Before: <img width="272" alt="Screenshot 2024-05-01 at 11 31 00 AM" src="https://github.com/Qiskit/documentation/assets/14852634/b80da918-526f-45ff-bd96-49a5585b3fbf"> After: <img width="266" alt="Screenshot 2024-05-01 at 11 32 41 AM" src="https://github.com/Qiskit/documentation/assets/14852634/396fa470-68a8-470d-b9d4-4f4f5c08cec6">
frankharkins · May 2, 2024 · e701cac · e701cac
1 parent d3a402f
commit e701cac
Show file tree

Hide file tree

Showing 20 changed files with 101 additions and 5 deletions.
diff --git 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": [

diff --git 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": [

diff --git 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": [

diff --git 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": [

diff --git 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": [

diff --git 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": [

diff --git 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": [

diff --git 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": [

diff --git 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": [

diff --git 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": [

diff --git 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": [

diff --git 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": [

diff --git 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": [

diff --git 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": [

diff --git 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": [

diff --git 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": [

diff --git 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
@@ -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
@@ -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
@@ -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) {