Allow packages to not have release notes (#1306)

The upcoming cloud transpiler client docs will not have release notes at first.
Qiskit · May 7, 2024 · 25befe2 · 25befe2
1 parent 96bcd5d
commit 25befe2
Show file tree

Hide file tree

Showing 5 changed files with 60 additions and 55 deletions.
diff --git a/scripts/lib/api/Pkg.ts b/scripts/lib/api/Pkg.ts
@@ -18,9 +18,11 @@ import { determineHistoricalQiskitGithubUrl } from "../qiskitMetapackage";
 import { TocGrouping } from "./TocGrouping";
 
 export class ReleaseNotesConfig {
+  readonly enabled: boolean;
   readonly separatePagesVersions: string[];
 
-  constructor(kwargs: { separatePagesVersions?: string[] }) {
+  constructor(kwargs: { enabled?: boolean; separatePagesVersions?: string[] }) {
+    this.enabled = kwargs.enabled ?? true;
     this.separatePagesVersions = kwargs.separatePagesVersions ?? [];
   }
 }

diff --git a/scripts/lib/api/__snapshots__/conversionPipeline.test.ts.snap b/scripts/lib/api/__snapshots__/conversionPipeline.test.ts.snap
@@ -36,10 +36,6 @@ exports[`qiskit-sphinx-theme: _toc 1`] = `
           "url": "/api/qiskit-sphinx-theme/inline_classes"
         }
       ]
-    },
-    {
-      "title": "Release notes",
-      "url": "/api/qiskit-sphinx-theme/release-notes"
     }
   ],
   "collapsed": true

diff --git a/scripts/lib/api/conversionPipeline.test.ts b/scripts/lib/api/conversionPipeline.test.ts
@@ -18,7 +18,7 @@ import { globby } from "globby";
 import { expect, test } from "@jest/globals";
 
 import { runConversionPipeline } from "./conversionPipeline";
-import { Pkg } from "./Pkg";
+import { Pkg, ReleaseNotesConfig } from "./Pkg";
 
 // This test uses snapshot testing (https://jestjs.io/docs/snapshot-testing#updating-snapshots). If the tests fail and the changes
 // are valid, run `npm test -- --updateSnapshot`.
@@ -58,6 +58,7 @@ test("qiskit-sphinx-theme", async () => {
     version: "0.1.1",
     versionWithoutPatch: "0.1",
     type: "latest",
+    releaseNotesConfig: new ReleaseNotesConfig({ enabled: false }),
   });
   const markdownFolder = pkg.outputDir(docsBaseFolder);
 

diff --git a/scripts/lib/api/generateToc.test.ts b/scripts/lib/api/generateToc.test.ts
@@ -273,7 +273,7 @@ describe("generateToc", () => {
     });
   });
 
-  test("TOC with distinct release note files", () => {
+  test("TOC with separate release note files", () => {
     const toc = generateToc(
       Pkg.mock({
         releaseNotesConfig: new ReleaseNotesConfig({
@@ -318,53 +318,54 @@ describe("generateToc", () => {
     });
   });
 
-  test("generate a toc without modules", () => {
-    const toc = generateToc(Pkg.mock({}), [
-      {
-        meta: { apiType: "class", apiName: "Sampler" },
-        url: "/api/my-quantum-project/my_quantum_project.Sampler",
-        ...DEFAULT_ARGS,
-      },
-      {
-        meta: { apiType: "method", apiName: "Sampler.run" },
-        url: "/api/my-quantum-project/my_quantum_project.Sampler.run",
-        ...DEFAULT_ARGS,
-      },
-      {
-        meta: { apiType: "class", apiName: "Estimator" },
-        url: "/api/my-quantum-project/my_quantum_project.Estimator",
-        ...DEFAULT_ARGS,
-      },
-      {
-        meta: { apiType: "class" },
-        url: "/api/my-quantum-project/my_quantum_project.NoName",
-        ...DEFAULT_ARGS,
-      },
-      {
-        meta: { apiType: "class", apiName: "Options" },
-        url: "docs/my_quantum_project.options.Options",
-        ...DEFAULT_ARGS,
-      },
-      {
-        meta: {
-          apiType: "function",
-          apiName: "runSomething",
+  test("generate a toc without modules and releaes notes", () => {
+    const toc = generateToc(
+      Pkg.mock({
+        releaseNotesConfig: new ReleaseNotesConfig({ enabled: false }),
+      }),
+      [
+        {
+          meta: { apiType: "class", apiName: "Sampler" },
+          url: "/api/my-quantum-project/my_quantum_project.Sampler",
+          ...DEFAULT_ARGS,
         },
-        url: "docs/my_quantum_project.runSomething",
-        ...DEFAULT_ARGS,
-      },
-    ]);
+        {
+          meta: { apiType: "method", apiName: "Sampler.run" },
+          url: "/api/my-quantum-project/my_quantum_project.Sampler.run",
+          ...DEFAULT_ARGS,
+        },
+        {
+          meta: { apiType: "class", apiName: "Estimator" },
+          url: "/api/my-quantum-project/my_quantum_project.Estimator",
+          ...DEFAULT_ARGS,
+        },
+        {
+          meta: { apiType: "class" },
+          url: "/api/my-quantum-project/my_quantum_project.NoName",
+          ...DEFAULT_ARGS,
+        },
+        {
+          meta: { apiType: "class", apiName: "Options" },
+          url: "docs/my_quantum_project.options.Options",
+          ...DEFAULT_ARGS,
+        },
+        {
+          meta: {
+            apiType: "function",
+            apiName: "runSomething",
+          },
+          url: "docs/my_quantum_project.runSomething",
+          ...DEFAULT_ARGS,
+        },
+      ],
+    );
 
     expect(toc).toEqual({
       children: [
         {
           title: "API index",
           url: "/api/my-quantum-project",
         },
-        {
-          title: "Release notes",
-          url: "/api/my-quantum-project/release-notes",
-        },
       ],
       collapsed: true,
       title: "My Quantum Project",

diff --git a/scripts/lib/api/generateToc.ts b/scripts/lib/api/generateToc.ts
@@ -46,27 +46,32 @@ export function generateToc(pkg: Pkg, results: HtmlToMdResultWithUrl[]): Toc {
 
   addItemsToModules(items, tocModulesByTitle, tocModuleTitles);
 
-  let sortedTocModules;
+  let orderedModules;
   if (pkg.tocGrouping) {
-    sortedTocModules = groupAndSortModules(pkg.tocGrouping, tocModulesByTitle);
+    orderedModules = groupAndSortModules(pkg.tocGrouping, tocModulesByTitle);
   } else if (pkg.nestModulesInToc) {
-    sortedTocModules = getNestedTocModulesSorted(
+    orderedModules = getNestedTocModulesSorted(
       tocModulesByTitle,
       tocModuleTitles,
     );
   } else {
-    sortedTocModules = sortAndTruncateModules(tocModules);
+    orderedModules = sortAndTruncateModules(tocModules);
   }
 
   generateOverviewPage(tocModules);
-  const maybeIndexPage = ensureIndexPage(pkg, sortedTocModules);
+  const maybeIndexPage = ensureIndexPage(pkg, orderedModules);
   if (maybeIndexPage) {
-    sortedTocModules.unshift(maybeIndexPage);
+    orderedModules.unshift(maybeIndexPage);
+  }
+
+  const maybeReleaseNotes = generateReleaseNotesEntry(pkg);
+  if (maybeReleaseNotes) {
+    orderedModules.push(maybeReleaseNotes);
   }
 
   return {
     title: pkg.title,
-    children: [...sortedTocModules, generateReleaseNotesEntries(pkg)],
+    children: orderedModules,
     collapsed: true,
   };
 }
@@ -266,7 +271,8 @@ function generateOverviewPage(tocModules: TocEntry[]): void {
   }
 }
 
-function generateReleaseNotesEntries(pkg: Pkg) {
+function generateReleaseNotesEntry(pkg: Pkg): TocEntry | undefined {
+  if (!pkg.releaseNotesConfig.enabled) return;
   const releaseNotesUrl = `/api/${pkg.name}/release-notes`;
   const releaseNotesEntry: TocEntry = {
     title: "Release notes",
@@ -280,7 +286,6 @@ function generateReleaseNotesEntries(pkg: Pkg) {
   } else {
     releaseNotesEntry.url = releaseNotesUrl;
   }
-
   return releaseNotesEntry;
 }