Add links to the Function/Class signatures

add back the titles

fix test

fix test 2

fix anchor

Author: arnaucasau

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

@@ -113,3 +113,71 @@ test("Pkg.determineGithubUrlFn()", () => {
     "https://github.com/qiskit/qiskit-ibmq-provider/tree/stable/0.18/qiskit/providers/ibmq/foo.py",
   );
 });
+
+test("Pkg.determineSignatureUrlFn()", () => {
+  const runtime = Pkg.mock({
+    name: "qiskit-ibm-runtime",
+    type: "latest",
+    versionWithoutPatch: "0.15",
+    kebabCaseAndShortenUrls: true,
+  }).determineSignatureUrlFn();
+
+  const qiskit = Pkg.mock({
+    name: "qiskit",
+    type: "latest",
+    versionWithoutPatch: "0.45",
+    kebabCaseAndShortenUrls: false,
+  }).determineSignatureUrlFn();
+
+  const historicalQiskit = Pkg.mock({
+    name: "qiskit",
+    type: "historical",
+    versionWithoutPatch: "0.32",
+    kebabCaseAndShortenUrls: false,
+  }).determineSignatureUrlFn();
+
+  const devQiskit = Pkg.mock({
+    name: "qiskit",
+    type: "dev",
+    version: "1.0.0-dev",
+    kebabCaseAndShortenUrls: false,
+  }).determineSignatureUrlFn();
+
+  const qiskitC = Pkg.mock({
+    name: "qiskit-c",
+    type: "latest",
+    versionWithoutPatch: "2.0.0",
+    kebabCaseAndShortenUrls: true,
+  }).determineSignatureUrlFn();
+
+  expect(runtime("../stubs/ibm_backend")).toEqual(
+    "/api/qiskit-ibm-runtime/ibm-backend",
+  );
+  expect(runtime("apidoc/qiskit-ibm-runtime.ibm_backend")).toEqual(
+    "/api/qiskit-ibm-runtime/ibm-backend",
+  );
+
+  expect(qiskit("../stubs/exceptions")).toEqual("/api/qiskit/exceptions");
+  expect(qiskit("apidocs/qasm2#anchor")).toEqual("/api/qiskit/qasm2#anchor");
+  expect(qiskit("/apidoc/qasm3")).toEqual("/api/qiskit/qasm3");
+  expect(qiskit("qiskit.transpiler.preset_passmanagers")).toEqual(
+    "/api/qiskit/qiskit.transpiler.preset_passmanagers",
+  );
+  expect(qiskit("#test")).toEqual("#test");
+
+  expect(devQiskit("../stubs/exceptions")).toEqual(
+    "/api/qiskit/dev/exceptions",
+  );
+
+  expect(historicalQiskit("../apidocs/preset_passmanager")).toEqual(
+    "/api/qiskit/0.32/preset_passmanager",
+  );
+  expect(
+    historicalQiskit("stubs/qiskit.transpiler.preset_passmanagers"),
+  ).toEqual("/api/qiskit/0.32/qiskit.transpiler.preset_passmanagers");
+
+  expect(qiskitC("#test")).toEqual("#test");
+  expect(qiskitC("cdoc/sparse_observable#test")).toEqual(
+    "/api/qiskit-c/sparse-observable#test",
+  );
+});

scripts/js/lib/api/Pkg.ts

@@ -19,6 +19,8 @@ import {
   QISKIT_TOC_GROUPING,
   QISKIT_ADDON_MPF_GROUPING,
 } from "./TocGrouping.js";
+import { removePart } from "../stringUtils.js";
+import { kebabCaseAndShortenPage } from "./normalizeResultUrls.js";
 
 export class ReleaseNotesConfig {
   readonly enabled: boolean;
@@ -273,6 +275,38 @@ export class Pkg {
     return `${this.title}${versionStr} release notes`;
   }
 
+  determineSignatureUrlFn(): (rawLink: string) => string {
+    let basePath = `/api/${this.name}`;
+    if (this.isHistorical()) basePath += `/${this.versionWithoutPatch}`;
+    if (this.isDev()) basePath += `/dev`;
+
+    return (rawLink: string) => {
+      if (rawLink.startsWith("http") || rawLink.startsWith("#")) return rawLink;
+
+      const [rawHref, rawAnchor] = rawLink.split("#", 2);
+
+      const href = removePart(rawHref, "/", [
+        "stubs",
+        "apidocs",
+        "apidoc",
+        "cdoc",
+        "..",
+      ]);
+
+      const segment = this.kebabCaseAndShortenUrls
+        ? kebabCaseAndShortenPage(href, this.name)
+        : href;
+
+      const anchor = rawAnchor ? `#${rawAnchor}` : "";
+      const link = `${segment}${anchor}`;
+
+      if (link.startsWith(basePath)) return link;
+
+      const separator = link.startsWith("/") ? "" : "/";
+      return `${basePath}${separator}${link}`;
+    };
+  }
+
   /**
    * Returns a function that takes in a fileName like `qiskit_ibm_runtime/job/exceptions` and returns the
    * stable GitHub URL to the file for this package's version.

scripts/js/lib/api/conversionPipeline.test.ts-snapshots/api-example.Electron

@@ -102,7 +102,7 @@ python_api_name: api_example.Electron
 
   ### overloaded\_func
 
-  <Function id="api_example.Electron.overloaded_func" signature="overloaded_func(arg1: tuple[str, str], arg2: list[str], arg3: int, arg4: Electron) → None" extraSignatures={["overloaded_func(arg1: tuple[int, int], arg2: list[int], arg3: bool, arg4: set[Electron]) → None"]}>
+  <Function id="api_example.Electron.overloaded_func" signature="overloaded_func(arg1: tuple[str, str], arg2: list[str], arg3: int, arg4: [Electron](#api_example.Electron)) → None" extraSignatures={["overloaded_func(arg1: tuple[int, int], arg2: list[int], arg3: bool, arg4: set[[Electron](#api_example.Electron)]) → None"]}>
     This is meant to test out [https://github.com/Qiskit/qiskit\_sphinx\_theme/pull/319](https://github.com/Qiskit/qiskit_sphinx_theme/pull/319).
 
     **Parameters**

scripts/js/lib/api/conversionPipeline.ts

@@ -107,6 +107,7 @@ async function convertFilesToMarkdown(
       html,
       fileName: file,
       determineGithubUrl: pkg.determineGithubUrlFn(),
+      determineSignatureUrl: pkg.determineSignatureUrlFn(),
       imageDestination: pkg.outputDir("/images"),
       releaseNotesTitle: pkg.releaseNotesTitle(),
       hasSeparateReleaseNotes: pkg.hasSeparateReleaseNotes(),

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

@@ -23,8 +23,13 @@ import { CheerioDoc } from "../testUtils.js";
 
 const RAW_SIGNATURE_EXAMPLE = `<span class='sig-prename descclassname'><span class='pre'>Estimator.</span></span><span class='sig-name descname'><span class='pre'>run</span></span><span class='sig-paren'>(</span><em class='sig-param'><span class='n'><span class='pre'>circuits</span></span></em>, <em class='sig-param'><span class='n'><span class='pre'>observables</span></span></em>, <em class='sig-param'><span class='n'><span class='pre'>parameter_values</span></span><span class='o'><span class='pre'>=</span></span><span class='default_value'><span class='pre'>None</span></span></em>, <em class='sig-param'><span class='o'><span class='pre'>**</span></span><span class='n'><span class='pre'>kwargs</span></span></em><span class='sig-paren'>)</span></dt>`;
 
+const determineSignatureUrl = (rawLink: string) => rawLink;
+
 test("htmlSignatureToMd", async () => {
-  const result = await htmlSignatureToMd(RAW_SIGNATURE_EXAMPLE);
+  const result = await htmlSignatureToMd(
+    RAW_SIGNATURE_EXAMPLE,
+    determineSignatureUrl,
+  );
   expect(result).toEqual(
     `Estimator.run(circuits, observables, parameter_values=None, **kwargs)`,
   );
@@ -71,7 +76,11 @@ test.describe("createOpeningTag()", () => {
       rawSignature: RAW_SIGNATURE_EXAMPLE,
     };
 
-    const tag = await createOpeningTag("Function", componentProps);
+    const tag = await createOpeningTag(
+      "Function",
+      componentProps,
+      determineSignatureUrl,
+    );
     expect(tag).toEqual(`<Function 
     id='qiskit_ibm_runtime.Estimator.run'
     attributeTypeHint='undefined'
@@ -92,7 +101,11 @@ test.describe("createOpeningTag()", () => {
       extraRawSignatures: [RAW_SIGNATURE_EXAMPLE, RAW_SIGNATURE_EXAMPLE],
     };
 
-    const tag = await createOpeningTag("Function", componentProps);
+    const tag = await createOpeningTag(
+      "Function",
+      componentProps,
+      determineSignatureUrl,
+    );
     expect(tag).toEqual(`<Function 
     id='qiskit_ibm_runtime.Estimator.run'
     attributeTypeHint='undefined'
@@ -113,7 +126,11 @@ test.describe("createOpeningTag()", () => {
       attributeValue: "None",
     };
 
-    const tag = await createOpeningTag("Attribute", componentProps);
+    const tag = await createOpeningTag(
+      "Attribute",
+      componentProps,
+      determineSignatureUrl,
+    );
     expect(tag).toEqual(`<Attribute 
     id='qiskit.circuit.QuantumCircuit.instance'
     attributeTypeHint='str | None'
@@ -132,7 +149,11 @@ test.describe("createOpeningTag()", () => {
       id: "qiskit.circuit.Sampler",
     };
 
-    const tag = await createOpeningTag("Class", componentProps);
+    const tag = await createOpeningTag(
+      "Class",
+      componentProps,
+      determineSignatureUrl,
+    );
     expect(tag).toEqual(`<Class 
     id='qiskit.circuit.Sampler'
     attributeTypeHint='undefined'

scripts/js/lib/api/generateApiComponents.ts

@@ -15,13 +15,16 @@ import { unified } from "unified";
 import rehypeParse from "rehype-parse";
 import rehypeRemark from "rehype-remark";
 import remarkStringify from "remark-stringify";
+import { visit } from "unist-util-visit";
+import { toText } from "hast-util-to-text";
 
 import { ApiType } from "./Metadata.js";
 import {
   getLastPartFromFullIdentifier,
   removeSuffix,
   APOSTROPHE_HEX_CODE,
 } from "../stringUtils.js";
+import { Root } from "mdast";
 
 export type ComponentProps = {
   id?: string;
@@ -52,6 +55,7 @@ export async function processMdxComponent(
   priorApiType: ApiType | undefined,
   apiType: Exclude<ApiType, "module">,
   id: string,
+  determineSignatureUrl: (rawLink: string) => string,
 ): Promise<[string, string]> {
   const tagName = APITYPE_TO_TAG[apiType];
 
@@ -71,7 +75,10 @@ export async function processMdxComponent(
   );
   addExtraSignatures(componentProps, extraProps);
 
-  return [await createOpeningTag(tagName, componentProps), `</${tagName}>`];
+  return [
+    await createOpeningTag(tagName, componentProps, determineSignatureUrl),
+    `</${tagName}>`,
+  ];
 }
 
 // ------------------------------------------------------------------
@@ -310,6 +317,7 @@ function prepareFunctionProps(
 export async function createOpeningTag(
   tagName: string,
   props: ComponentProps,
+  determineSignatureUrl: (rawLink: string) => string,
 ): Promise<string> {
   const attributeTypeHint = props.attributeTypeHint?.replaceAll(
     "'",
@@ -319,10 +327,15 @@ export async function createOpeningTag(
     "'",
     APOSTROPHE_HEX_CODE,
   );
-  const signature = await htmlSignatureToMd(props.rawSignature!);
+  const signature = await htmlSignatureToMd(
+    props.rawSignature!,
+    determineSignatureUrl,
+  );
   const extraSignatures: string[] = [];
   for (const sig of props.extraRawSignatures ?? []) {
-    extraSignatures.push(`"${await htmlSignatureToMd(sig!)}"`);
+    extraSignatures.push(
+      `"${await htmlSignatureToMd(sig!, determineSignatureUrl)}"`,
+    );
   }
 
   return `<${tagName} 
@@ -398,14 +411,43 @@ export function addExtraSignatures(
  */
 export async function htmlSignatureToMd(
   signatureHtml: string,
+  determineSignatureUrl: (rawLink: string) => string,
 ): Promise<string> {
   if (!signatureHtml) {
     return "";
   }
 
+  // The `code` tag helps us remove some undesired elements like asterisks surrounding
+  // the parameters.
   const html = `<code>${signatureHtml}</code>`;
   const file = await unified()
     .use(rehypeParse)
+    .use(() => (tree: Root) => {
+      visit(tree, { tagName: "a" }, (node: any) => {
+        // We transform the links into markdown as `text` nodes to avoid losing them once
+        // transforming the signature from HTML to markdown. This could happen because we
+        // have the signatures inside a `code` element. Moreover, we have more freedom by
+        // manually creating the links.
+        if (!node.properties?.href || !node.children?.length) {
+          return;
+        }
+
+        // We encode some conflicting characters that could make the markdown link break
+        // by using URL-encoding form.
+        const href = determineSignatureUrl(node.properties.href)
+          .replaceAll('"', "%22")
+          .replaceAll("(", "%28")
+          .replaceAll(")", "%29");
+        const isExternal = href.startsWith("http");
+        const title = node.properties.title;
+
+        // We only show the title if it's from an external link
+        const link = title && isExternal ? `${href} "${title}"` : `${href}`;
+
+        node.type = "text";
+        node.value = `[${toText(node.children[0])}](${link})`;
+      });
+    })
     .use(rehypeRemark)
     .use(remarkStringify)
     .process(html);

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

@@ -20,6 +20,7 @@ const DEFAULT_ARGS = {
     `https://github.com/Qiskit/qiskit-ibm-runtime/tree/0.9.2/${fileName}.py`,
   releaseNotesTitle: "My Quantum release notes",
   hasSeparateReleaseNotes: false,
+  determineSignatureUrl: (rawLink: string) => rawLink,
 };
 
 async function toMd(

scripts/js/lib/api/htmlToMd.ts

@@ -35,6 +35,7 @@ export async function sphinxHtmlToMarkdown(options: {
   fileName: string;
   imageDestination: string;
   determineGithubUrl: (fileName: string) => string;
+  determineSignatureUrl: (rawLink: string) => string;
   releaseNotesTitle: string;
   hasSeparateReleaseNotes: boolean;
   isCApi: boolean;