From 74ca7808bb9ece3fd9fbb3d66cbca24384fee7de Mon Sep 17 00:00:00 2001 From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> Date: Tue, 7 May 2024 08:35:54 -0400 Subject: [PATCH] Allow packages to not have release notes (#1306) The upcoming cloud transpiler client docs will not have release notes at first. --- scripts/lib/api/Pkg.ts | 4 +- .../conversionPipeline.test.ts.snap | 4 - scripts/lib/api/conversionPipeline.test.ts | 3 +- scripts/lib/api/generateToc.test.ts | 81 ++++++++++--------- scripts/lib/api/generateToc.ts | 23 +++--- 5 files changed, 60 insertions(+), 55 deletions(-) diff --git a/scripts/lib/api/Pkg.ts b/scripts/lib/api/Pkg.ts index 350881657a4..d4b57c8dcea 100644 --- 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 index f0cbbba2fad..c43769ae6e7 100644 --- 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 index 54ffdd8e5cf..2b8ea1fedfd 100644 --- 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 index 3aea2de5db2..d480d166b70 100644 --- 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,42 +318,47 @@ 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: [ @@ -361,10 +366,6 @@ describe("generateToc", () => { 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 index f8e8cc9f4e5..03d57a25c29 100644 --- 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; }