techdocs: use README.md as index fallback

Signed-off-by: Vincenzo Scamporlino <me@vinzscam.dev>

packages/techdocs-common/src/stages/generate/helpers.test.ts

@@ -27,6 +27,7 @@ import {
   getGeneratorKey,
   getMkdocsYml,
   getRepoUrlFromLocationAnnotation,
+  patchIndexPreBuild,
   patchMkdocsYmlPreBuild,
   storeEtagMetadata,
   validateMkdocsYaml,
@@ -286,6 +287,58 @@ describe('helpers', () => {
     });
   });
 
+  describe('patchIndexPreBuild', () => {
+    it('should have no effect if docs/index.md exists', async () => {
+      mockFs({
+        '/docs/index.md': 'index.md content',
+        '/docs/README.md': 'docs/README.md content',
+      });
+
+      await patchIndexPreBuild({ inputDir: '/', logger: mockLogger });
+
+      expect(fs.readFileSync('/docs/index.md', 'utf-8')).toEqual(
+        'index.md content',
+      );
+      mockFs.restore();
+    });
+
+    it("should use docs/README.md if docs/index.md doesn't exists", async () => {
+      mockFs({
+        '/docs/README.md': 'docs/README.md content',
+        '/README.md': 'main README.md content',
+      });
+
+      await patchIndexPreBuild({ inputDir: '/', logger: mockLogger });
+
+      expect(fs.readFileSync('/docs/index.md', 'utf-8')).toEqual(
+        'docs/README.md content',
+      );
+      mockFs.restore();
+    });
+
+    it('should use README.md if neither docs/index.md or docs/README.md exist', async () => {
+      mockFs({
+        '/README.md': 'main README.md content',
+      });
+
+      await patchIndexPreBuild({ inputDir: '/', logger: mockLogger });
+
+      expect(fs.readFileSync('/docs/index.md', 'utf-8')).toEqual(
+        'main README.md content',
+      );
+      mockFs.restore();
+    });
+
+    it('should not use any file as index.md if no one matches the requirements', async () => {
+      mockFs({});
+
+      await patchIndexPreBuild({ inputDir: '/', logger: mockLogger });
+
+      expect(() => fs.readFileSync('/docs/index.md', 'utf-8')).toThrow();
+      mockFs.restore();
+    });
+  });
+
   describe('addBuildTimestampMetadata', () => {
     beforeEach(() => {
       mockFs.restore();

packages/techdocs-common/src/stages/generate/helpers.ts

@@ -286,6 +286,46 @@ export const patchMkdocsYmlPreBuild = async (
   }
 };
 
+/**
+ * Update docs/index.md file before TechDocs generator uses it to generate docs site,
+ * falling back to docs/README.md or README.md in case a default docs/index.md
+ * is not provided.
+ */
+export const patchIndexPreBuild = async ({
+  inputDir,
+  logger,
+}: {
+  inputDir: string;
+  logger: Logger;
+}) => {
+  const docsPath = path.join(inputDir, 'docs');
+  const indexMdPath = path.join(docsPath, 'index.md');
+
+  try {
+    await fs.promises.access(indexMdPath);
+    return;
+  } catch {
+    logger.warn('docs/index.md not found.');
+  }
+  const fallbacks = [
+    path.join(docsPath, 'README.md'),
+    path.join(inputDir, 'README.md'),
+  ];
+
+  await fs.promises.mkdir(docsPath, { recursive: true });
+  for (const filePath of fallbacks) {
+    try {
+      await fs.copyFile(filePath, indexMdPath);
+      return;
+    } catch (error) {
+      logger.warn(`${path.relative(inputDir, filePath)} not found.`);
+    }
+  }
+  logger.warn(
+    `Could not find any techdocs' index file. Please make sure at least one of docs/index.md docs/README.md README.md exists.`,
+  );
+};
+
 /**
  * Update the techdocs_metadata.json to add a new build timestamp metadata. Create the .json file if it doesn't exist.
  *

packages/techdocs-common/src/stages/generate/techdocs.ts

@@ -25,6 +25,7 @@ import {
 import {
   addBuildTimestampMetadata,
   getMkdocsYml,
+  patchIndexPreBuild,
   patchMkdocsYmlPreBuild,
   runCommand,
   storeEtagMetadata,
@@ -102,6 +103,7 @@ export class TechdocsGenerator implements GeneratorBase {
         parsedLocationAnnotation,
         this.scmIntegrations,
       );
+      await patchIndexPreBuild({ inputDir, logger: childLogger });
     }
 
     // Directories to bind on container