From 6826c1a974ebc6da4472ef74d79c51f08b2a0a83 Mon Sep 17 00:00:00 2001
From: Arnau Casau <47946624+arnaucasau@users.noreply.github.com>
Date: Fri, 8 Dec 2023 17:44:47 +0100
Subject: [PATCH] Fix span tag id=undefined and fix /api/qiskit/index entry
 (#500)

This PR fixes the issue with the undefined span IDs when generating the
documentation and transforms the `/api/qiskit/index` entry in the toc
file to `/api/qiskit`. A new test has been added to verify we don't
generate span tags with an undefined id.

The Qiskit docs have been regenerated to verify the correct behavior of
the script for the current version. The changes in the docs files are
empty lines matching the great work done by @Eric-Arellano in #484
removing the tags manually.

Closes #485
Closes #227
---
 docs/api/qiskit-ibm-provider/_toc.json        |  2 +-
 docs/api/qiskit-ibm-runtime/0.14/_toc.json    |  2 +-
 docs/api/qiskit-ibm-runtime/0.15/_toc.json    |  2 +-
 docs/api/qiskit-ibm-runtime/_toc.json         |  2 +-
 .../qiskit.algorithms.eigensolvers.VQD.md     |  4 --
 docs/api/qiskit/qiskit.providers.BackendV1.md |  2 -
 ...skit.providers.basicaer.QasmSimulatorPy.md |  2 -
 ...oviders.basicaer.StatevectorSimulatorPy.md |  2 -
 ...t.providers.basicaer.UnitarySimulatorPy.md |  2 -
 ...t.transpiler.passes.NoiseAdaptiveLayout.md | 22 --------
 scripts/lib/sphinx/generateToc.ts             |  3 +-
 .../lib/sphinx/sphinxHtmlToMarkdown.test.ts   | 53 +++++++++++++++++++
 scripts/lib/sphinx/sphinxHtmlToMarkdown.ts    |  2 +-
 13 files changed, 60 insertions(+), 40 deletions(-)

diff --git a/docs/api/qiskit-ibm-provider/_toc.json b/docs/api/qiskit-ibm-provider/_toc.json
index 9c2d7a636d2..8f6d84ea1ff 100644
--- a/docs/api/qiskit-ibm-provider/_toc.json
+++ b/docs/api/qiskit-ibm-provider/_toc.json
@@ -6,7 +6,7 @@
       "children": [
         {
           "title": "Overview",
-          "url": "/api/qiskit-ibm-provider/index"
+          "url": "/api/qiskit-ibm-provider"
         },
         {
           "title": "IBMBackend",
diff --git a/docs/api/qiskit-ibm-runtime/0.14/_toc.json b/docs/api/qiskit-ibm-runtime/0.14/_toc.json
index d72632182bc..16d099fd880 100644
--- a/docs/api/qiskit-ibm-runtime/0.14/_toc.json
+++ b/docs/api/qiskit-ibm-runtime/0.14/_toc.json
@@ -6,7 +6,7 @@
       "children": [
         {
           "title": "Overview",
-          "url": "/api/qiskit-ibm-runtime/0.14/index"
+          "url": "/api/qiskit-ibm-runtime/0.14/"
         },
         {
           "title": "Estimator",
diff --git a/docs/api/qiskit-ibm-runtime/0.15/_toc.json b/docs/api/qiskit-ibm-runtime/0.15/_toc.json
index 2e6950b925e..02767b0ff3f 100644
--- a/docs/api/qiskit-ibm-runtime/0.15/_toc.json
+++ b/docs/api/qiskit-ibm-runtime/0.15/_toc.json
@@ -6,7 +6,7 @@
       "children": [
         {
           "title": "Overview",
-          "url": "/api/qiskit-ibm-runtime/0.15/index"
+          "url": "/api/qiskit-ibm-runtime/0.15"
         },
         {
           "title": "Estimator",
diff --git a/docs/api/qiskit-ibm-runtime/_toc.json b/docs/api/qiskit-ibm-runtime/_toc.json
index e25b60ba260..5a3360beddc 100644
--- a/docs/api/qiskit-ibm-runtime/_toc.json
+++ b/docs/api/qiskit-ibm-runtime/_toc.json
@@ -6,7 +6,7 @@
       "children": [
         {
           "title": "Overview",
-          "url": "/api/qiskit-ibm-runtime/index"
+          "url": "/api/qiskit-ibm-runtime"
         },
         {
           "title": "Estimator",
diff --git a/docs/api/qiskit/qiskit.algorithms.eigensolvers.VQD.md b/docs/api/qiskit/qiskit.algorithms.eigensolvers.VQD.md
index c1d7956b0a3..c5e295d4b98 100644
--- a/docs/api/qiskit/qiskit.algorithms.eigensolvers.VQD.md
+++ b/docs/api/qiskit/qiskit.algorithms.eigensolvers.VQD.md
@@ -68,8 +68,6 @@ A classical optimizer or a list of optimizers,
 
 [Optimizer](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer") | Sequence\[[Optimizer](qiskit.algorithms.optimizers.Optimizer "qiskit.algorithms.optimizers.Optimizer")]
 
-
-
 ### one for every k-th eigenvalue. Can either be a Qiskit optimizer or a callable
 
 that takes an array as input and returns a Qiskit or SciPy optimization result.
@@ -94,8 +92,6 @@ Beta parameters in the VQD paper. Should have length k - 1, with k the number of
 
 [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.12)")]
 
-
-
 ### initial point
 
 An optional initial point (i.e. initial parameter values) or a list of initial points (one for every k-th eigenvalue) for the optimizer. If `None` then VQD will look to the ansatz for a preferred point and if not will simply compute a random one.
diff --git a/docs/api/qiskit/qiskit.providers.BackendV1.md b/docs/api/qiskit/qiskit.providers.BackendV1.md
index c98deed198b..0bf3f8dd120 100644
--- a/docs/api/qiskit/qiskit.providers.BackendV1.md
+++ b/docs/api/qiskit/qiskit.providers.BackendV1.md
@@ -56,8 +56,6 @@ Initialize a backend class
 
 In addition to the public abstract methods, subclasses should also implement the following private methods:
 
-
-
 `abstract classmethod _default_options()`
 
 Return the default options
diff --git a/docs/api/qiskit/qiskit.providers.basicaer.QasmSimulatorPy.md b/docs/api/qiskit/qiskit.providers.basicaer.QasmSimulatorPy.md
index 3ac44b0ded0..ef670a728a4 100644
--- a/docs/api/qiskit/qiskit.providers.basicaer.QasmSimulatorPy.md
+++ b/docs/api/qiskit/qiskit.providers.basicaer.QasmSimulatorPy.md
@@ -30,8 +30,6 @@ Initialize a backend class
 
 In addition to the public abstract methods, subclasses should also implement the following private methods:
 
-
-
 `classmethod _default_options()`
 
 Return the default options
diff --git a/docs/api/qiskit/qiskit.providers.basicaer.StatevectorSimulatorPy.md b/docs/api/qiskit/qiskit.providers.basicaer.StatevectorSimulatorPy.md
index eb402766df4..52b3dd407d3 100644
--- a/docs/api/qiskit/qiskit.providers.basicaer.StatevectorSimulatorPy.md
+++ b/docs/api/qiskit/qiskit.providers.basicaer.StatevectorSimulatorPy.md
@@ -30,8 +30,6 @@ Initialize a backend class
 
 In addition to the public abstract methods, subclasses should also implement the following private methods:
 
-
-
 `classmethod _default_options()`
 
 Return the default options
diff --git a/docs/api/qiskit/qiskit.providers.basicaer.UnitarySimulatorPy.md b/docs/api/qiskit/qiskit.providers.basicaer.UnitarySimulatorPy.md
index 09ae27dc9ee..9cca511804d 100644
--- a/docs/api/qiskit/qiskit.providers.basicaer.UnitarySimulatorPy.md
+++ b/docs/api/qiskit/qiskit.providers.basicaer.UnitarySimulatorPy.md
@@ -30,8 +30,6 @@ Initialize a backend class
 
 In addition to the public abstract methods, subclasses should also implement the following private methods:
 
-
-
 `classmethod _default_options()`
 
 Return the default options
diff --git a/docs/api/qiskit/qiskit.transpiler.passes.NoiseAdaptiveLayout.md b/docs/api/qiskit/qiskit.transpiler.passes.NoiseAdaptiveLayout.md
index ddb8a341910..570c00a693a 100644
--- a/docs/api/qiskit/qiskit.transpiler.passes.NoiseAdaptiveLayout.md
+++ b/docs/api/qiskit/qiskit.transpiler.passes.NoiseAdaptiveLayout.md
@@ -20,12 +20,8 @@ Choose a noise-adaptive Layout based on current calibration data for the backend
 >
 > The pass implements the qubit mapping method from: Noise-Adaptive Compiler Mappings for Noisy Intermediate-Scale Quantum Computers Prakash Murali, Jonathan M. Baker, Ali Javadi-Abhari, Frederic T. Chong, Margaret R. Martonosi ASPLOS 2019 (arXiv:1901.11054).
 
-
-
 `Ordering of edges`
 
-
-
 `Map qubits edge-by-edge in the order of decreasing frequency of occurrence in the program dag.`
 
 ### Initialization
@@ -34,40 +30,22 @@ Choose a noise-adaptive Layout based on current calibration data for the backend
 
 `Initialization()`
 
-
-
 `If an edge exists with both endpoints unmapped,`
 
-
-
 `pick the best available hardware cx to execute this edge.`
 
-
-
 `Iterative step`
 
-
-
 `When an edge exists with one endpoint unmapped,`
 
-
-
 `map that endpoint to a location which allows`
 
-
-
 `maximum reliability for CNOTs with previously mapped qubits.`
 
-
-
 `In the end if there are unmapped qubits (which don't`
 
-
-
 `participate in any CNOT), map them to any available`
 
-
-
 `hardware qubit.`
 
 ### Notes
diff --git a/scripts/lib/sphinx/generateToc.ts b/scripts/lib/sphinx/generateToc.ts
index 2f47daf685c..a69c7d6c75e 100644
--- a/scripts/lib/sphinx/generateToc.ts
+++ b/scripts/lib/sphinx/generateToc.ts
@@ -54,7 +54,8 @@ export function generateToc(
     const tocModules = modules.map(
       (module): TocEntry => ({
         title: module.meta.python_api_name!,
-        url: module.url,
+        // Remove the final /index from the url
+        url: module.url.replace(/\/index$/, ""),
       }),
     );
     const tocModulesByTitle = keyBy(tocModules, (toc) => toc.title);
diff --git a/scripts/lib/sphinx/sphinxHtmlToMarkdown.test.ts b/scripts/lib/sphinx/sphinxHtmlToMarkdown.test.ts
index d8144baee5a..0646ecbafe0 100644
--- a/scripts/lib/sphinx/sphinxHtmlToMarkdown.test.ts
+++ b/scripts/lib/sphinx/sphinxHtmlToMarkdown.test.ts
@@ -1470,6 +1470,59 @@ test("identify release notes", async () => {
 `);
 });
 
+// This test checks that the conversion to markdown is correct when we have a <dt class=sig-object"> tag
+// without id. For more information: https://github.com/Qiskit/documentation/issues/485
+test("test dt tag without id", async () => {
+  expect(
+    await toMd(`
+    <div role="main">
+    <p>In addition to the public abstract methods, subclasses should also implement the following
+    private methods:</p>
+    <dl class="py method">
+    <dt class="sig sig-object py">
+    <em class="property"><span class="pre">classmethod</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">_default_options</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/qiskit/providers/basicaer/qasm_simulator.html#QasmSimulatorPy._default_options"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
+    <dd><p>Return the default options</p>
+    <p>This method will return a <a class="reference internal" href="qiskit.providers.Options.html#qiskit.providers.Options" title="qiskit.providers.Options"><code class="xref py py-class docutils literal notranslate"><span class="pre">qiskit.providers.Options</span></code></a>
+    subclass object that will be used for the default options. These
+    should be the default parameters to use for the options of the
+    backend.</p>
+    <dl class="field-list simple">
+    <dt class="field-odd">Returns<span class="colon">:</span></dt>
+    <dd class="field-odd"><p><dl class="simple">
+    <dt>A options object with</dt><dd><p>default values set</p>
+    </dd>
+    </dl>
+    </p>
+    </dd>
+    <dt class="field-even">Return type<span class="colon">:</span></dt>
+    <dd class="field-even"><p><a class="reference internal" href="qiskit.providers.Options.html#qiskit.providers.Options" title="qiskit.providers.Options">qiskit.providers.Options</a></p>
+    </dd>
+    </dl>
+    </dd></dl>
+    </div>
+`),
+  ).toMatchInlineSnapshot(`
+  "In addition to the public abstract methods, subclasses should also implement the following private methods:
+  
+  \`classmethod _default_options()\`
+  
+  Return the default options
+  
+  This method will return a [\`qiskit.providers.Options\`](qiskit.providers.Options#qiskit.providers.Options "qiskit.providers.Options") subclass object that will be used for the default options. These should be the default parameters to use for the options of the backend.
+  
+  **Returns**
+  
+  **A options object with**
+  
+  default values set
+  
+  **Return type**
+  
+  [qiskit.providers.Options](qiskit.providers.Options#qiskit.providers.Options "qiskit.providers.Options")
+  "
+  `);
+});
+
 async function toMd(html: string) {
   return (
     await sphinxHtmlToMarkdown({
diff --git a/scripts/lib/sphinx/sphinxHtmlToMarkdown.ts b/scripts/lib/sphinx/sphinxHtmlToMarkdown.ts
index ae129b14964..f5523cd58ce 100644
--- a/scripts/lib/sphinx/sphinxHtmlToMarkdown.ts
+++ b/scripts/lib/sphinx/sphinxHtmlToMarkdown.ts
@@ -193,7 +193,7 @@ export async function sphinxHtmlToMarkdown(options: {
       .map((child) => {
         const $child = $page(child);
         $child.find(".viewcode-link").closest("a").remove();
-        const id = $dl.find("dt.sig-object").attr("id");
+        const id = $dl.find("dt.sig-object").attr("id") || "";
 
         if (child.name === "dt" && $dl.hasClass("class")) {
           if (!meta.python_api_type) {