Don't delete API docs for class aliases (Qiskit#815)

Part of Qiskit#814. We shouldn't be deleting attribute pages if they don't correspond to an owning class. This PR also runs `npm run regen-apis`; as shown, this PR's logic change only impacts Qiskit v1 docs.
frankharkins · Feb 15, 2024 · 2b1c26d · 2b1c26d
1 parent 829851c
commit 2b1c26d
Show file tree

Hide file tree

Showing 10 changed files with 63 additions and 31 deletions.
diff --git a/docs/api/qiskit-ibm-provider/0.7/_toc.json b/docs/api/qiskit-ibm-provider/0.7/_toc.json
@@ -211,4 +211,3 @@
   ],
   "collapsed": true
 }
-
diff --git a/docs/api/qiskit-ibm-runtime/0.18/_toc.json b/docs/api/qiskit-ibm-runtime/0.18/_toc.json
@@ -514,4 +514,3 @@
   ],
   "collapsed": true
 }
-
diff --git a/docs/api/qiskit/dev/primitives.md b/docs/api/qiskit/dev/primitives.md
@@ -224,11 +224,11 @@ print([q.binary_probabilities() for q in job_result.quasi_dists])
 
 ## Estimator
 
-|                                                                                                                         |                                                                                                                                                   |
-| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`BaseEstimator`](qiskit.primitives.BaseEstimator#qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator")    | alias of `BaseEstimatorV1`                                                                                                                        |
-| [`Estimator`](qiskit.primitives.Estimator "qiskit.primitives.Estimator")(\*\[, options])                                | Reference implementation of [`BaseEstimator`](qiskit.primitives.BaseEstimator#qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator"). |
-| [`BackendEstimator`](qiskit.primitives.BackendEstimator "qiskit.primitives.BackendEstimator")(backend\[, options, ...]) | Evaluates expectation value using Pauli rotation gates.                                                                                           |
+|                                                                                                                         |                                                                                                                   |
+| ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| [`BaseEstimator`](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator")                                    | alias of `BaseEstimatorV1`                                                                                        |
+| [`Estimator`](qiskit.primitives.Estimator "qiskit.primitives.Estimator")(\*\[, options])                                | Reference implementation of [`BaseEstimator`](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator"). |
+| [`BackendEstimator`](qiskit.primitives.BackendEstimator "qiskit.primitives.BackendEstimator")(backend\[, options, ...]) | Evaluates expectation value using Pauli rotation gates.                                                           |
 
 ## EstimatorV2
 
@@ -241,7 +241,7 @@ print([q.binary_probabilities() for q in job_result.quasi_dists])
 
 |                                                                                                                   |                                                                                                                  |
 | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| [`BaseSampler`](qiskit.primitives.BaseSampler#qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler")      | alias of `BaseSamplerV1`                                                                                         |
+| [`BaseSampler`](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler")                                    | alias of `BaseSamplerV1`                                                                                         |
 | [`Sampler`](qiskit.primitives.Sampler "qiskit.primitives.Sampler")(\*\[, options])                                | Sampler class.                                                                                                   |
 | [`BackendSampler`](qiskit.primitives.BackendSampler "qiskit.primitives.BackendSampler")(backend\[, options, ...]) | A `BaseSampler` implementation that provides an interface for leveraging the sampler interface from any backend. |
 

diff --git a/docs/api/qiskit/dev/qiskit.primitives.BaseEstimator.md b/docs/api/qiskit/dev/qiskit.primitives.BaseEstimator.md
@@ -0,0 +1,12 @@
+---
+title: BaseEstimator
+description: API reference for qiskit.primitives.BaseEstimator
+in_page_toc_min_heading_level: 1
+python_api_type: attribute
+python_api_name: qiskit.primitives.BaseEstimator
+---
+
+# BaseEstimator
+
+alias of `BaseEstimatorV1`
+
diff --git a/docs/api/qiskit/dev/qiskit.primitives.BaseSampler.md b/docs/api/qiskit/dev/qiskit.primitives.BaseSampler.md
@@ -0,0 +1,12 @@
+---
+title: BaseSampler
+description: API reference for qiskit.primitives.BaseSampler
+in_page_toc_min_heading_level: 1
+python_api_type: attribute
+python_api_name: qiskit.primitives.BaseSampler
+---
+
+# BaseSampler
+
+alias of `BaseSamplerV1`
+
diff --git a/docs/api/qiskit/dev/qiskit.primitives.Estimator.md b/docs/api/qiskit/dev/qiskit.primitives.Estimator.md
@@ -14,7 +14,7 @@ python_api_name: qiskit.primitives.Estimator
 
 Bases: `BaseEstimatorV1`\[`PrimitiveJob`\[[`EstimatorResult`](qiskit.primitives.EstimatorResult "qiskit.primitives.base.estimator_result.EstimatorResult")]]
 
-Reference implementation of [`BaseEstimator`](qiskit.primitives.BaseEstimator#qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator").
+Reference implementation of [`BaseEstimator`](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator").
 
 **Run Options**
 

diff --git a/docs/api/qiskit/dev/qiskit.primitives.Sampler.md b/docs/api/qiskit/dev/qiskit.primitives.Sampler.md
@@ -16,7 +16,7 @@ Bases: `BaseSamplerV1`\[`PrimitiveJob`\[[`SamplerResult`](qiskit.primitives.Samp
 
 Sampler class.
 
-[`Sampler`](#qiskit.primitives.Sampler "qiskit.primitives.Sampler") is a reference implementation of [`BaseSampler`](qiskit.primitives.BaseSampler#qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler").
+[`Sampler`](#qiskit.primitives.Sampler "qiskit.primitives.Sampler") is a reference implementation of [`BaseSampler`](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler").
 
 **Run Options**
 

diff --git a/public/api/qiskit/dev/objects.inv b/public/api/qiskit/dev/objects.inv
diff --git a/scripts/lib/api/mergeClassMembers.test.ts b/scripts/lib/api/mergeClassMembers.test.ts
@@ -13,10 +13,11 @@
 import { describe, expect, test } from "@jest/globals";
 
 import { mergeClassMembers } from "./mergeClassMembers";
+import { HtmlToMdResultWithUrl } from "./HtmlToMdResult";
 
 describe("mergeClassMembers", () => {
   test("merge class members", async () => {
-    const results: Parameters<typeof mergeClassMembers>[0] = [
+    const results: HtmlToMdResultWithUrl[] = [
       {
         markdown: `## Attributes
 
@@ -130,7 +131,7 @@ Validate options.
   });
 
   test("merge class with methods already inlined", async () => {
-    const results: Parameters<typeof mergeClassMembers>[0] = [
+    const results: HtmlToMdResultWithUrl[] = [
       {
         markdown: `## Attributes
 
@@ -185,4 +186,23 @@ Inlined method
 `);
     expect(merged.length).toEqual(1);
   });
+
+  test("keep members without an owning class", async () => {
+    // Regression test for https://github.com/Qiskit/documentation/issues/814.
+    const results: HtmlToMdResultWithUrl[] = [
+      {
+        markdown:
+          '<span id="baseestimator" />\n\n# BaseEstimator\n\nalias of `BaseEstimatorV1`\n',
+        meta: {
+          apiType: "attribute",
+          apiName: "qiskit.primitives.BaseEstimator",
+        },
+        images: [],
+        isReleaseNotes: false,
+        url: "/docs/api/qiskit/qiskit.primitives.BaseEstimator",
+      },
+    ];
+    const merged = await mergeClassMembers(results);
+    expect(merged).toEqual(results);
+  });
 });
diff --git a/scripts/lib/api/mergeClassMembers.ts b/scripts/lib/api/mergeClassMembers.ts
@@ -10,7 +10,7 @@
 // copyright notice, and modified files need to carry a notice indicating
 // that they have been altered from the originals.
 
-import { includes, isEmpty, orderBy, reject } from "lodash";
+import { includes, isEmpty, orderBy } from "lodash";
 import { unified } from "unified";
 import remarkParse from "remark-parse";
 import remarkMdx from "remark-mdx";
@@ -32,21 +32,16 @@ export async function mergeClassMembers<T extends HtmlToMdResultWithUrl>(
   const classes = resultsWithName.filter(
     (result) => result.meta.apiType === "class",
   );
+  const mergedMemberUrls = new Set();
 
   for (const clazz of classes) {
-    const members = orderBy(
-      resultsWithName.filter((result) => {
-        if (
-          !includes(
-            ["method", "property", "attribute", "function"],
-            result.meta.apiType,
-          )
-        )
-          return false;
-        return result.meta.apiName?.startsWith(`${clazz.meta.apiName}.`);
-      }),
-      (result) => result.meta.apiName,
+    const unsortedMembers = resultsWithName.filter(
+      (result) =>
+        includes(["method", "property", "attribute"], result.meta.apiType) &&
+        result.meta.apiName?.startsWith(`${clazz.meta.apiName}.`),
     );
+    unsortedMembers.forEach((result) => mergedMemberUrls.add(result.url));
+    const members = orderBy(unsortedMembers, (result) => result.meta.apiName);
 
     const attributesAndProps = members.filter(
       (member) =>
@@ -94,12 +89,7 @@ export async function mergeClassMembers<T extends HtmlToMdResultWithUrl>(
     }
   }
 
-  // remove merged results
-  const finalResults = reject(results, (result) =>
-    includes(["method", "attribute", "property"], result.meta.apiType),
-  );
-
-  return finalResults;
+  return results.filter((result) => !mergedMemberUrls.has(result.url));
 }
 
 async function replaceMembersAfterTitle(