Disable objects.inv for historical API docs (Qiskit#656)

This is meant to unblock regenerating the Qiskit API docs. But more
generally, I think it's not a necessary feature to support for now.

1. I've never seen a project's conf.py not point to latest
2. I'm not confident it even works with pointing to the correct
subfoler. (That's ignorance - it might work!)
3. We can add this mechanism in the future whenever we want

scripts/commands/convertApiDocsToHistorical.ts

@@ -79,7 +79,6 @@ zxMain(async () => {
     projectNewHistoricalFolder,
   );
   await copyImages(pkgName, versionWithoutPatch);
-  await copyObjectsInv(pkgName, versionWithoutPatch);
 });
 
 async function copyApiDocsAndUpdateLinks(
@@ -144,14 +143,6 @@ async function copyImages(pkgName: string, versionWithoutPatch: string) {
   await $`find ${imageDirSource}/* -maxdepth 0 -type f | grep -v "release_notes" | xargs -I {} cp -a {} ${imageDirDest}`;
 }
 
-async function copyObjectsInv(pkgName: string, versionWithoutPatch: string) {
-  console.log("Copying objects.inv");
-  const sourceDir = `${getRoot()}/public/api/${pkgName}`;
-  const destDir = `${getRoot()}/public/api/${pkgName}/${versionWithoutPatch}`;
-  await mkdirp(destDir);
-  await $`cp -a ${sourceDir}/objects.inv ${destDir}`;
-}
-
 async function updateLinksFile(
   pkgName: string,
   versionWithoutPatch: string,

scripts/commands/updateApiDocs.ts

@@ -127,7 +127,9 @@ async function convertHtmlToMarkdown(
   markdownPath: string,
   pkg: Pkg,
 ) {
-  const objectsInv = await ObjectsInv.fromFile(htmlPath);
+  const maybeObjectsInv = await (pkg.hasObjectsInv()
+    ? ObjectsInv.fromFile(htmlPath)
+    : undefined);
   const files = await globby(
     [
       "apidocs/**.html",
@@ -185,11 +187,11 @@ async function convertHtmlToMarkdown(
   results = await mergeClassMembers(results);
   flattenFolders(results);
   specialCaseResults(results);
-  await updateLinks(results, objectsInv, pkg.transformLink);
+  await updateLinks(results, maybeObjectsInv, pkg.transformLink);
   await dedupeHtmlIdsFromResults(results);
   addFrontMatter(results, pkg);
 
-  await objectsInv.write(pkg.outputDir("public"));
+  await maybeObjectsInv?.write(pkg.outputDir("public"));
   for (const result of results) {
     let path = urlToPath(result.url);
 

scripts/lib/api/Pkg.ts

@@ -155,6 +155,18 @@ export class Pkg {
     return `${getRoot()}/.out/python/sources/${this.name}/${this.version}`;
   }
 
+  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
+    // of the historical Qiskit API docs <0.32 did not include `objects.inv`, so we could
+    // never get the mechanism working for those.
+    //
+    // 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;
+  }
+
   /**
    * Returns a function that takes in a fileName like `qiskit_ibm_provider/job/exceptions` and returns the
    * stable GitHub URL to the file for this package's version.

scripts/lib/api/updateLinks.ts

@@ -97,7 +97,7 @@ export function updateUrl(
 
 export async function updateLinks(
   results: HtmlToMdResultWithUrl[],
-  objectsInv: ObjectsInv,
+  maybeObjectsInv?: ObjectsInv,
   transformLink?: (link: Link) => Link | undefined,
 ): Promise<void> {
   const resultsByName = keyBy(results, (result) => result.meta.apiName!);
@@ -139,7 +139,7 @@ export async function updateLinks(
     result.markdown = output?.toString();
   }
 
-  objectsInv.updateUris((uri: string) =>
+  maybeObjectsInv?.updateUris((uri: string) =>
     updateUrl(uri, resultsByName, itemNames),
   );
 }