Fix anchor links in API docs to inline class methods (#2218)

Closes #2210. Before, cross references to inlined class methods would try using the link `InlineClass.some_method`, but the link should really be `some_method` without `InlineClass`. The better fix is #2215 because it avoids the risk of ambiguous anchors. However, it would be a UX regression to land that until #1395 is done. Fixing this is tracked by #2217.
Qiskit · Nov 1, 2024 · 283ca70 · 283ca70
1 parent 277826f
commit 283ca70
Show file tree

Hide file tree

Showing 9 changed files with 25 additions and 15 deletions.
diff --git a/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata.mdx b/docs/api/qiskit-addon-obp/utils-metadata-obp-metadata.mdx
@@ -58,7 +58,7 @@ python_api_name: qiskit_addon_obp.utils.metadata.OBPMetadata
 
     This method computes the accumulated error for a given observable index at a given “time” during the course of the backpropagation. In this context, “time” is to be understood as the discrete steps of already backpropagated slices.
 
-    The accumulated error is computed as the sum of the individual [`SliceMetadata.slice_errors`](utils-metadata-slice-metadata#slice_errors "qiskit_addon_obp.utils.metadata.SliceMetadata.slice_errors"). These in turn may be computed within a specified [`TruncationErrorBudget.p_norm`](utils-truncating#TruncationErrorBudget.p_norm "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.p_norm"). Thus, the computed accumulated error is an upper bound to the real accumulated error as given by the [Minkowski inequality](https://en.wikipedia.org/wiki/Minkowski_inequality) (the generalization of the triangle inequality for Lp-norms other than `p=2`).
+    The accumulated error is computed as the sum of the individual [`SliceMetadata.slice_errors`](utils-metadata-slice-metadata#slice_errors "qiskit_addon_obp.utils.metadata.SliceMetadata.slice_errors"). These in turn may be computed within a specified [`TruncationErrorBudget.p_norm`](utils-truncating#p_norm "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.p_norm"). Thus, the computed accumulated error is an upper bound to the real accumulated error as given by the [Minkowski inequality](https://en.wikipedia.org/wiki/Minkowski_inequality) (the generalization of the triangle inequality for Lp-norms other than `p=2`).
 
     <Admonition title="Note" type="note">
       Since a general Lp-norm (other than `p=2`) is *not* an inner product norm, it does *not* satisfy the [parallelogram law](https://en.wikipedia.org/wiki/Parallelogram_law). Hence, we must use the Minkowski inequality as the upper bound of the accumulated error.
@@ -103,7 +103,7 @@ python_api_name: qiskit_addon_obp.utils.metadata.OBPMetadata
 
     This method computes the left-over error budget for a given observable index at a given “time” during the course of the backpropagation. In this context, “time” is to be understood as the discrete steps of already backpropagated slices.
 
-    The left-over error budget is computed as the remainder of the total budget minus the sum of the individual [`SliceMetadata.slice_errors`](utils-metadata-slice-metadata#slice_errors "qiskit_addon_obp.utils.metadata.SliceMetadata.slice_errors"). These in turn may be computed within a specified [`TruncationErrorBudget.p_norm`](utils-truncating#TruncationErrorBudget.p_norm "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.p_norm").
+    The left-over error budget is computed as the remainder of the total budget minus the sum of the individual [`SliceMetadata.slice_errors`](utils-metadata-slice-metadata#slice_errors "qiskit_addon_obp.utils.metadata.SliceMetadata.slice_errors"). These in turn may be computed within a specified [`TruncationErrorBudget.p_norm`](utils-truncating#p_norm "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.p_norm").
 
     <Admonition title="Note" type="note">
       See also the explanations in [`accumulated_error()`](#qiskit_addon_obp.utils.metadata.OBPMetadata.accumulated_error "qiskit_addon_obp.utils.metadata.OBPMetadata.accumulated_error") for more details on how the individual slice errors are summed up to form an upper bound to the real error via the Minkowski inequality.

diff --git a/docs/api/qiskit-addon-obp/utils-metadata-slice-metadata.mdx b/docs/api/qiskit-addon-obp/utils-metadata-slice-metadata.mdx
@@ -63,7 +63,7 @@ python_api_name: qiskit_addon_obp.utils.metadata.SliceMetadata
     The sum of the coefficients for each observable that were trimmed during operator simplification because each individual coefficient was below the trimming threshold.
 
     <Admonition title="Warning" type="caution">
-      This sum is *not* affected by the value of [`p_norm`](utils-truncating#TruncationErrorBudget.p_norm "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.p_norm")!
+      This sum is *not* affected by the value of [`p_norm`](utils-truncating#p_norm "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.p_norm")!
     </Admonition>
 
     <Admonition title="Note" type="note">

diff --git a/docs/api/qiskit-ibm-runtime/0.31/_toc.json b/docs/api/qiskit-ibm-runtime/0.31/_toc.json
@@ -514,4 +514,3 @@
   ],
   "collapsed": true
 }
-
diff --git a/public/api/qiskit-addon-mpf/objects.inv b/public/api/qiskit-addon-mpf/objects.inv
diff --git a/public/api/qiskit-addon-obp/objects.inv b/public/api/qiskit-addon-obp/objects.inv
diff --git a/public/api/qiskit-addon-utils/objects.inv b/public/api/qiskit-addon-utils/objects.inv
diff --git a/scripts/js/lib/api/updateLinks.test.ts b/scripts/js/lib/api/updateLinks.test.ts
@@ -31,6 +31,8 @@ test.describe("updateLinks", () => {
 [link8](#qiskit_ibm_runtime.RuntimeJob.job)
 [link9](https://qiskit.org/documentation/apidoc/algorithms.html)
 [link10](https://qiskit.org/documentation/stubs/qiskit.circuit.BreakLoopOp.html#assemble)
+[link11](qiskit_ibm_runtime.RuntimeJob#qiskit_ibm_runtime.RuntimeJob.a_method)
+[link12](qiskit_ibm_runtime.RuntimeJob#qiskit_ibm_runtime.RuntimeJob.InlineClass.another_method)
         `,
       meta: {
         apiType: "class",
@@ -97,7 +99,9 @@ test.describe("updateLinks", () => {
 [link7](qiskit_ibm_runtime.RuntimeJob)
 [link8](#qiskit_ibm_runtime.RuntimeJob.job)
 [link9](/api/qiskit/algorithms)
-[link10](/api/qiskit/qiskit.circuit.BreakLoopOp#assemble)\n`,
+[link10](/api/qiskit/qiskit.circuit.BreakLoopOp#assemble)
+[link11](qiskit_ibm_runtime.RuntimeJob#a_method)
+[link12](qiskit_ibm_runtime.RuntimeJob#another_method)\n`,
         meta: {
           apiName: "qiskit_ibm_runtime.RuntimeJob",
           apiType: "class",
@@ -149,7 +153,9 @@ test.describe("updateLinks", () => {
 [link7](runtime-job)
 [link8](#qiskit_ibm_runtime.RuntimeJob.job)
 [link9](/api/qiskit/algorithms)
-[link10](/api/qiskit/qiskit.circuit.BreakLoopOp#assemble)\n`,
+[link10](/api/qiskit/qiskit.circuit.BreakLoopOp#assemble)
+[link11](runtime-job#a_method)
+[link12](runtime-job#another_method)\n`,
         meta: {
           apiName: "qiskit_ibm_runtime.RuntimeJob",
           apiType: "class",

diff --git a/scripts/js/lib/api/updateLinks.ts b/scripts/js/lib/api/updateLinks.ts
@@ -92,9 +92,21 @@ export function normalizeUrl(
       url = normalizedUrlWithoutHash;
     }
 
+    // Rather than linking to the component like `Function` or `Attribute`, we link to the header.
+    // This is necessary because until we implement https://github.com/Qiskit/documentation/issues/1395, the
+    // anchor for the component would take you too low in the page, given that the header is above the component.
     // qiskit_ibm_runtime.RuntimeJob#qiskit_ibm_runtime.RuntimeJob.job -> qiskit_ibm_runtime.RuntimeJob#job
+    //
+    // TODO(#2217): Remove this special case and use the full ID instead.
     if (hash?.startsWith(`${page}.`)) {
-      const member = removePrefix(hash, `${page}.`);
+      let member = removePrefix(hash, `${page}.`);
+      // Also check for inline classes, which often show up on module pages.
+      // qiskit_addon_obp.utils.truncating#qiskit_addon_obp.utils.truncating.TruncationErrorBudget.p_norm
+      // -> qiskit_addon_obp.utils.truncating#p_norm, whereas without this check
+      // it would be qiskit_addon_obp.utils.truncating#TruncationErrorBudget.p_norm.
+      if (member.includes(".")) {
+        member = member.split(".", 2)[1];
+      }
       url = `${normalizedUrlWithoutHash}#${member}`;
     }
   }

diff --git a/scripts/js/lib/links/ignores.ts b/scripts/js/lib/links/ignores.ts
@@ -340,14 +340,7 @@ const FILES_TO_IGNORES__EXPECTED: FilesToIgnores = mergeFilesToIgnores(
   _legacyQiskitSDKIssues(),
 );
 
-const FILES_TO_IGNORES__SHOULD_FIX: FilesToIgnores = {
-  "docs/api/qiskit-addon-obp/utils-metadata-obp-metadata.mdx": [
-    "utils-truncating#TruncationErrorBudget.p_norm",
-  ],
-  "docs/api/qiskit-addon-obp/utils-metadata-slice-metadata.mdx": [
-    "utils-truncating#TruncationErrorBudget.p_norm",
-  ],
-};
+const FILES_TO_IGNORES__SHOULD_FIX: FilesToIgnores = {};
 
 export const FILES_TO_IGNORES: FilesToIgnores = mergeFilesToIgnores(
   FILES_TO_IGNORES__EXPECTED,