Refactor of Pkg to add a package type (Qiskit#775)

Part of Qiskit#316 

This PR replaces the `historical` attribute of the class `Pkg` for an
attribute named `type` which will allow us to know if the package
version is the latest one or the historical one. This small refactor is
convenient to avoid having a bunch of boolean attributes when the
version types `dev` and `stable` are introduced.

Different version types will have different behaviors in our API
generation script like a custom path (e.g. numerical subfolder or `dev`
subfolder).

scripts/commands/updateApiDocs.ts

@@ -91,11 +91,13 @@ zxMain(async () => {
     );
   }
 
+  const type = args.historical ? "historical" : "latest";
+
   const pkg = await Pkg.fromArgs(
     args.package,
     args.version,
     versionMatch[0],
-    args.historical,
+    type,
   );
 
   const artifactFolder = pkg.ciArtifactFolder();
@@ -106,7 +108,7 @@ zxMain(async () => {
   }
 
   const outputDir = pkg.outputDir(`${getRoot()}/docs`);
-  if (pkg.historical && !(await pathExists(outputDir))) {
+  if (pkg.isHistorical() && !(await pathExists(outputDir))) {
     await mkdirp(outputDir);
   } else {
     console.log(
@@ -163,7 +165,7 @@ async function convertHtmlToMarkdown(
     results.push({ ...result, url });
 
     if (
-      !pkg.historical &&
+      !pkg.isHistorical() &&
       pkg.hasSeparateReleaseNotes &&
       file.endsWith("release_notes.html")
     ) {
@@ -198,7 +200,7 @@ async function convertHtmlToMarkdown(
     // modify the current API's file.
     if (
       !pkg.hasSeparateReleaseNotes &&
-      pkg.historical &&
+      pkg.isHistorical() &&
       path.endsWith("release-notes.md")
     ) {
       continue;
@@ -228,11 +230,11 @@ async function convertHtmlToMarkdown(
 
   // Add the new release entry to the _toc.json for all historical API versions.
   // We don't need to add any entries in projects with a single release notes file.
-  if (!pkg.historical && pkg.hasSeparateReleaseNotes) {
+  if (!pkg.isHistorical() && pkg.hasSeparateReleaseNotes) {
     await updateHistoricalTocFiles(pkg);
   }
 
-  if (!pkg.historical && pkg.hasSeparateReleaseNotes) {
+  if (!pkg.isHistorical() && pkg.hasSeparateReleaseNotes) {
     console.log("Generating release-notes/index");
     const markdown = generateReleaseNotesIndex(pkg);
     await writeFile(`${markdownPath}/release-notes/index.md`, markdown);
@@ -245,7 +247,7 @@ async function convertHtmlToMarkdown(
     JSON.stringify(pkg_json, null, 2) + "\n",
   );
 
-  if (!pkg.historical || (await pathExists(`${htmlPath}/_images`))) {
+  if (!pkg.isHistorical() || (await pathExists(`${htmlPath}/_images`))) {
     // Some historical versions don't have the `_images` folder in the artifact store in Box (https://ibm.ent.box.com/folder/246867452622)
     console.log("Saving images");
     await saveImages(allImages, `${htmlPath}/_images`, pkg);

scripts/lib/api/Pkg.ts

@@ -29,6 +29,8 @@ export interface ReleaseNoteEntry {
   url: string;
 }
 
+type PackageType = "latest" | "historical";
+
 /**
  * Information about the specific package and version we're dealing with, e.g. qiskit 0.45.
  */
@@ -40,7 +42,7 @@ export class Pkg {
   readonly transformLink?: (link: Link) => Link | undefined;
   readonly version: string;
   readonly versionWithoutPatch: string;
-  readonly historical: boolean;
+  readonly type: PackageType;
   readonly releaseNoteEntries: ReleaseNoteEntry[];
 
   static VALID_NAMES = ["qiskit", "qiskit-ibm-runtime", "qiskit-ibm-provider"];
@@ -53,7 +55,7 @@ export class Pkg {
     transformLink?: (link: Link) => Link | undefined;
     version: string;
     versionWithoutPatch: string;
-    historical: boolean;
+    type: PackageType;
     releaseNoteEntries: ReleaseNoteEntry[];
   }) {
     this.name = kwargs.name;
@@ -63,21 +65,21 @@ export class Pkg {
     this.transformLink = kwargs.transformLink;
     this.version = kwargs.version;
     this.versionWithoutPatch = kwargs.versionWithoutPatch;
-    this.historical = kwargs.historical;
+    this.type = kwargs.type;
     this.releaseNoteEntries = kwargs.releaseNoteEntries;
   }
 
   static async fromArgs(
     name: string,
     version: string,
     versionWithoutPatch: string,
-    historical: boolean,
+    type: PackageType,
   ): Promise<Pkg> {
     const args = {
       name,
       version,
       versionWithoutPatch,
-      historical,
+      type,
     };
 
     if (name === "qiskit") {
@@ -127,7 +129,7 @@ export class Pkg {
     transformLink?: (link: Link) => Link | undefined;
     version?: string;
     versionWithoutPatch?: string;
-    historical?: boolean;
+    type?: PackageType;
     releaseNoteEntries?: ReleaseNoteEntry[];
   }): Pkg {
     return new Pkg({
@@ -138,14 +140,14 @@ export class Pkg {
       transformLink: kwargs.transformLink,
       version: kwargs.version ?? "0.1.0",
       versionWithoutPatch: kwargs.versionWithoutPatch ?? "0.1",
-      historical: kwargs.historical ?? false,
+      type: kwargs.type ?? "latest",
       releaseNoteEntries: kwargs.releaseNoteEntries ?? [],
     });
   }
 
   outputDir(parentDir: string): string {
     let path = join(parentDir, "api", this.name);
-    if (this.historical) {
+    if (this.isHistorical()) {
       path = join(path, this.versionWithoutPatch);
     }
     return path;
@@ -155,6 +157,10 @@ export class Pkg {
     return `${getRoot()}/.out/python/sources/${this.name}/${this.version}`;
   }
 
+  isHistorical(): boolean {
+    return this.type == "historical";
+  }
+
   hasObjectsInv(): boolean {
     // We don't currently worry about objects.inv for historical API docs because we don't
     // expect users to care about it, so we can keep things simple. For example, our copy
@@ -164,7 +170,7 @@ export class Pkg {
     // Feel free to enable this mechanism for historical API docs if users find it useful!
     // When adding, be sure that we correctly point to the correct subfolder, e.g.
     // api/qiskit/0.44 rather than api/qiskit.
-    return !this.historical;
+    return !this.isHistorical();
   }
 
   /**

scripts/lib/api/saveImages.ts

@@ -31,7 +31,7 @@ export async function saveImages(
   await pMap(images, async (img) => {
     // The release notes images are only saved in the current version to
     // avoid having duplicate files.
-    if (img.fileName.includes("release_notes") && pkg.historical) {
+    if (img.fileName.includes("release_notes") && pkg.isHistorical()) {
       return;
     }