Incorporate feedback

Author: frankharkins

scripts/js/lib/api/processHtml.test.ts

@@ -285,7 +285,7 @@ test("addLanguageClassToCodeBlocks()", () => {
   // as with this example. Also this name is misleading. Really what we are doing here is dealing with RST's `.. parsed-literal ::`
   // (https://docutils.sourceforge.io/docs/ref/rst/directives.html#parsed-literal-block), which we tend to use to put code literals
   // along with gate text representations like the above.
-  addLanguageClassToCodeBlocks(doc1.$, doc1.$main, false);
+  addLanguageClassToCodeBlocks(doc1.$, doc1.$main, { isCApi: false });
   doc1.expectHtml(`<p><strong>Circuit symbol:</strong></p>
     <div class="highlight-default notranslate"><div class="highlight"><pre><code class="language-python"><span></span>     ┌──────────┐
     q_0: ┤ U(ϴ,φ,λ) ├
@@ -302,7 +302,7 @@ test("addLanguageClassToCodeBlocks()", () => {
       </pre>
       </div>
     </div>`);
-  addLanguageClassToCodeBlocks(doc2.$, doc2.$main, false);
+  addLanguageClassToCodeBlocks(doc2.$, doc2.$main, { isCApi: false });
   doc2.expectHtml(`<div class="highlight-default notranslate">
       <div class="highlight">
       <pre><code class="language-python"><span></span><span class="kn">from</span> <span class="nn">qiskit_ibm_runtime.options</span> <span class="kn">import</span> <span class="n">Options</span>
@@ -400,7 +400,7 @@ test.describe("maybeSetModuleMetadata()", () => {
     const html = `<h1>Hello</h1>`;
     const meta: Metadata = {};
     const doc = CheerioDoc.load(html);
-    maybeSetModuleMetadata(doc.$, doc.$main, meta, false);
+    maybeSetModuleMetadata(doc.$, doc.$main, meta, { isCApi: false });
     doc.expectHtml(html);
     expect(meta).toEqual({});
   });
@@ -412,7 +412,7 @@ test.describe("maybeSetModuleMetadata()", () => {
   ): void => {
     const meta: Metadata = {};
     const doc = CheerioDoc.load(html);
-    maybeSetModuleMetadata(doc.$, doc.$main, meta, isCApi);
+    maybeSetModuleMetadata(doc.$, doc.$main, meta, { isCApi });
     doc.expectHtml(html);
     expect(meta).toEqual({
       apiType: "module",
@@ -515,7 +515,7 @@ backends may not have this attribute.</p>
 `;
     const doc = CheerioDoc.load(html);
     const meta: Metadata = {};
-    await processMembersAndSetMeta(doc.$, doc.$main, meta, false);
+    await processMembersAndSetMeta(doc.$, doc.$main, meta, { isCApi: false });
     doc.expectHtml(`<h1>least_busy</h1>
 <div><function id="qiskit_ibm_provider.least_busy" attributetypehint="undefined" attributevalue="undefined" isdedicatedpage="true" github="../_modules/qiskit_ibm_provider.html#least_busy" signature="least_busy(backends)¶" modifiers="" extrasignatures="[]">
   
@@ -575,7 +575,7 @@ particular error, which subclasses both <a class="reference internal" href="#qis
 `;
     const doc = CheerioDoc.load(html);
     const meta: Metadata = {};
-    await processMembersAndSetMeta(doc.$, doc.$main, meta, false);
+    await processMembersAndSetMeta(doc.$, doc.$main, meta, { isCApi: false });
     doc.expectHtml(`<span class="target" id="module-qiskit.exceptions"><span id="qiskit-exceptions"></span></span><section id="top-level-exceptions-qiskit-exceptions">
 <h1>Top-level exceptions (<a class="reference internal" href="#module-qiskit.exceptions" title="qiskit.exceptions"><code class="xref py py-mod docutils literal notranslate"><span class="pre">qiskit.exceptions</span></code></a>)<a class="headerlink" href="#top-level-exceptions-qiskit-exceptions" title="Permalink to this heading">¶</a></h1>
 <p>All Qiskit-related errors raised by Qiskit are subclasses of the base:</p>
@@ -621,7 +621,7 @@ marked as builtins since they are not actually present in any include file this
 `;
     const doc = CheerioDoc.load(html);
     const meta: Metadata = { apiType: "module", apiName: "my_module" };
-    await processMembersAndSetMeta(doc.$, doc.$main, meta, false);
+    await processMembersAndSetMeta(doc.$, doc.$main, meta, { isCApi: false });
     doc.expectHtml(`
 <h3 data-header-type="attribute-header">qiskit.qasm2.LEGACY_CUSTOM_INSTRUCTIONS¶</h3><div><attribute id="qiskit.qasm2.LEGACY_CUSTOM_INSTRUCTIONS" attributetypehint="" attributevalue="" isdedicatedpage="undefined" github="undefined" signature="" modifiers="" extrasignatures="[]">
   
@@ -661,7 +661,7 @@ marked as builtins since they are not actually present in any include file this
 </dd></dl>`;
     const doc = CheerioDoc.load(html);
     const meta: Metadata = {};
-    await processMembersAndSetMeta(doc.$, doc.$main, meta, true);
+    await processMembersAndSetMeta(doc.$, doc.$main, meta, { isCApi: true });
     doc.expectHtml(`<h3 data-header-type=\"method-header\">qk_obs_identity</h3><div><function id=\"qk_obs_identity\" attributetypehint=\"undefined\" attributevalue=\"undefined\" isdedicatedpage=\"undefined\" github=\"undefined\" signature=\"QkSparseObservable *qk_obs_identity(uint32_t num_qubits)¶\" modifiers=\"\" extrasignatures=\"[]\">
   
 <div><p>Construct the identity observable.</p>

scripts/js/lib/api/processHtml.ts

@@ -27,15 +27,17 @@ export type ProcessedHtml = {
   isReleaseNotes: boolean;
 };
 
-export async function processHtml(options: {
+interface ProcessHtmlOptions {
   html: string;
   fileName: string;
   imageDestination: string;
   determineGithubUrl: (fileName: string) => string;
   releaseNotesTitle: string;
   hasSeparateReleaseNotes: boolean;
   isCApi: boolean;
-}): Promise<ProcessedHtml> {
+}
+
+export async function processHtml(options: ProcessHtmlOptions): Promise<ProcessedHtml> {
   const {
     html,
     fileName,
@@ -68,7 +70,7 @@ export async function processHtml(options: {
   removeDownloadSourceCode($main);
   removeMatplotlibFigCaptions($main);
   handleSphinxDesignCards($, $main);
-  addLanguageClassToCodeBlocks($, $main, isCApi);
+  addLanguageClassToCodeBlocks($, $main, options);
   replaceViewcodeLinksWithGitHub($, $main, determineGithubUrl);
   updateRedirectedExternalLinks($, $main, externalRedirects);
   convertRubricsToHeaders($, $main);
@@ -78,8 +80,8 @@ export async function processHtml(options: {
   preserveMathBlockWhitespace($, $main);
 
   const meta: Metadata = {};
-  await processMembersAndSetMeta($, $main, meta, isCApi);
-  maybeSetModuleMetadata($, $main, meta, isCApi);
+  await processMembersAndSetMeta($, $main, meta, options);
+  maybeSetModuleMetadata($, $main, meta, options);
   if (meta.apiType === "module") {
     updateModuleHeadings($, $main);
   }
@@ -183,8 +185,8 @@ export function handleSphinxDesignCards(
   });
 }
 
-function detectLanguage($pre: Cheerio<any>, isCApi: boolean): string | null {
-  const defaultLanguage = isCApi ? "c" : "python";
+function detectLanguage($pre: Cheerio<any>, options: { isCApi: boolean }): string | null {
+  const defaultLanguage = options.isCApi ? "c" : "python";
   // Two levels up from `pre` should have class `highlight-<language>`
   const detectedLanguage = $pre
     .parent()
@@ -201,11 +203,11 @@ function detectLanguage($pre: Cheerio<any>, isCApi: boolean): string | null {
 export function addLanguageClassToCodeBlocks(
   $: CheerioAPI,
   $main: Cheerio<any>,
-  isCApi: boolean,
+  options: { isCApi: boolean },
 ): void {
   $main.find("pre").each((_, pre) => {
     const $pre = $(pre);
-    const language = detectLanguage($pre, isCApi);
+    const language = detectLanguage($pre, options);
     const languageClass = language ? `language-${language}` : "";
     $pre.replaceWith(
       `<pre><code class="${languageClass}">${$pre.html()}</code></pre>`,
@@ -339,7 +341,7 @@ export async function processMembersAndSetMeta(
   $: CheerioAPI,
   $main: Cheerio<any>,
   meta: Metadata,
-  isCApi: boolean,
+  options: { isCApi: boolean },
 ): Promise<void> {
   let continueMapMembers = true;
   while (continueMapMembers) {
@@ -359,10 +361,11 @@ export async function processMembersAndSetMeta(
 
     const $dl = $(dl);
     const id =
-      (isCApi
+      (options.isCApi
         ? // IDs in the C API have a bunch of extra information (e.g.
           // `_CPPv415qk_obs_free8uint32_t`) whereas we just want to display the
-          // function name (e.g. `qk_obs_free`).
+          // function name (e.g. `qk_obs_free`). This is safe because C does not
+          // have function overloading so the function name is unique.
           $dl.find("span.sig-name.descname").text()
         : $dl.find("dt").attr("id")) || "";
     const apiType = getApiType($dl);
@@ -411,9 +414,9 @@ export function maybeSetModuleMetadata(
   $: CheerioAPI,
   $main: Cheerio<any>,
   meta: Metadata,
-  isCApi: boolean,
+  options: { isCApi: boolean },
 ): void {
-  const modulePrefix = isCApi ? "group__" : "module-";
+  const modulePrefix = options.isCApi ? "group__" : "module-";
   const moduleIdWithPrefix = $main
     .find("span, section, div.section")
     .toArray()