Large refactor

Signed-off-by: Andre Wanlin <67169551+awanlin@users.noreply.github.com>

plugins/techdocs-node/api-report.md

@@ -54,7 +54,7 @@ export type GeneratorRunOptions = {
   etag?: string;
   logger: Logger;
   logStream?: Writable;
-  entity: Entity;
+  siteName?: string;
 };
 
 // @public
@@ -86,6 +86,15 @@ export const getLocationForEntity: (
   scmIntegration: ScmIntegrationRegistry,
 ) => ParsedLocationAnnotation;
 
+// @public
+export const getMkdocsYml: (
+  inputDir: string,
+  siteName?: string,
+) => Promise<{
+  path: string;
+  content: string;
+}>;
+
 // @public
 export type MigrateRequest = {
   removeOriginal?: boolean;

plugins/techdocs-node/src/stages/generate/__fixtures__/mkdocs_default.yml

@@ -1,4 +1,4 @@
 site_name: Test site name
 docs_dir: docs
 plugins:
-  - techdocs-core
+  - techdocs-core

plugins/techdocs-node/src/stages/generate/helpers.test.ts

@@ -524,7 +524,7 @@ describe('helpers', () => {
       mockFs({ [key]: mkdocsYml });
       const { path: mkdocsPath, content } = await getMkdocsYml(
         inputDir,
-        mockEntity,
+        mockEntity.metadata.title,
       );
 
       expect(mkdocsPath).toBe(key);
@@ -536,7 +536,7 @@ describe('helpers', () => {
       mockFs({ [key]: mkdocsYml });
       const { path: mkdocsPath, content } = await getMkdocsYml(
         inputDir,
-        mockEntity,
+        mockEntity.metadata.title,
       );
       expect(mkdocsPath).toBe(key);
       expect(content).toBe(mkdocsYml.toString());
@@ -547,7 +547,7 @@ describe('helpers', () => {
       mockFs({ [key]: mkdocsDefaultYml });
       const { path: mkdocsPath, content } = await getMkdocsYml(
         inputDir,
-        mockEntity,
+        mockEntity.metadata.title,
       );
       expect(mkdocsPath).toBe(key);
       expect(content).toBe(mkdocsDefaultYml.toString());
@@ -555,7 +555,9 @@ describe('helpers', () => {
 
     it('throws when neither .yml nor .yaml nor default file is present', async () => {
       const invalidInputDir = resolvePath(__filename);
-      await expect(getMkdocsYml(invalidInputDir, mockEntity)).rejects.toThrow(
+      await expect(
+        getMkdocsYml(invalidInputDir, mockEntity.metadata.title),
+      ).rejects.toThrow(
         /Could not read MkDocs YAML config file mkdocs.yml or mkdocs.yaml or default for validation/,
       );
     });

plugins/techdocs-node/src/stages/generate/helpers.ts

@@ -150,16 +150,50 @@ export const MKDOCS_SCHEMA = DEFAULT_SCHEMA.extend([
   }),
 ]);
 
+/**
+ * Generates a mkdocs.yml configuration file
+ *
+ * @param inputDir - base dir to where the mkdocs.yml file will be created
+ * @param siteName - name of site to be used in mkdocs.yml for the
+ * required `site_name` property, default value is "Table of Contents"
+ */
+export const generateMkdocsYml = async (
+  inputDir: string,
+  siteName?: string,
+) => {
+  try {
+    // TODO(awanlin): Use a provided default mkdocs.yml
+    // from config or some specified location. If this is
+    // not provided then fall back to generating bare
+    // minimum mkdocs.yml file
+
+    const mkdocsYmlPath = path.join(inputDir, 'mkdocs.yml');
+    const defaultSiteName = siteName ?? 'Table of Contents';
+    const defaultMkdocsContent =
+      `site_name: ${defaultSiteName}\n` +
+      'docs_dir: docs\n' +
+      'plugins:\n' +
+      '  - techdocs-core\n';
+
+    await fs.writeFile(mkdocsYmlPath, defaultMkdocsContent);
+  } catch (error) {
+    throw new ForwardedError('Could not generate mkdocs.yml file', error);
+  }
+};
+
 /**
  * Finds and loads the contents of either an mkdocs.yml or mkdocs.yaml file,
  * depending on which is present (MkDocs supports both as of v1.2.2).
+ * @public
  *
  * @param inputDir - base dir to be searched for either an mkdocs.yml or
  *   mkdocs.yaml file.
+ * @param siteName - name of site to be used in mkdocs.yml for the
+ * required `site_name` property, default value is "Table of Contents"
  */
 export const getMkdocsYml = async (
   inputDir: string,
-  entity: Entity,
+  siteName?: string,
 ): Promise<{ path: string; content: string }> => {
   let mkdocsYmlPath: string;
   let mkdocsYmlFileString: string;
@@ -182,14 +216,8 @@ export const getMkdocsYml = async (
       };
     }
 
-    // No mkdocs file, use default
-    const defaultMkdocsContent =
-      `site_name: ${entity.metadata.title ?? entity.metadata.name}\n` +
-      'docs_dir: docs\n' +
-      'plugins:\n' +
-      '  - techdocs-core\n';
-
-    await fs.writeFile(mkdocsYmlPath, defaultMkdocsContent);
+    // No mkdocs file, generate it
+    await generateMkdocsYml(inputDir, siteName);
     mkdocsYmlFileString = await fs.readFile(mkdocsYmlPath, 'utf8');
   } catch (error) {
     throw new ForwardedError(

plugins/techdocs-node/src/stages/generate/index.ts

@@ -15,6 +15,7 @@
  */
 export { TechdocsGenerator } from './techdocs';
 export { Generators } from './generators';
+export { getMkdocsYml } from './helpers';
 export type {
   GeneratorBase,
   GeneratorOptions,

plugins/techdocs-node/src/stages/generate/techdocs.ts

@@ -96,13 +96,13 @@ export class TechdocsGenerator implements GeneratorBase {
       etag,
       logger: childLogger,
       logStream,
-      entity,
+      siteName,
     } = options;
 
     // Do some updates to mkdocs.yml before generating docs e.g. adding repo_url
     const { path: mkdocsYmlPath, content } = await getMkdocsYml(
       inputDir,
-      entity,
+      siteName,
     );
 
     // validate the docs_dir first

plugins/techdocs-node/src/stages/generate/types.ts

@@ -53,6 +53,7 @@ export type GeneratorConfig = {
  * @param etag - A unique identifier for the prepared tree e.g. commit SHA. If provided it will be stored in techdocs_metadata.json.
  * @param logger - A logger that forwards the messages to the caller to be displayed outside of the backend.
  * @param logStream - A log stream that can send raw log messages to the caller to be displayed outside of the backend.
+ * @param siteName - Name of the site to be used in mkdocs.yml for the required `site_name` property, default value is "Table of Contents"
  */
 export type GeneratorRunOptions = {
   inputDir: string;
@@ -61,7 +62,7 @@ export type GeneratorRunOptions = {
   etag?: string;
   logger: Logger;
   logStream?: Writable;
-  entity: Entity;
+  siteName?: string;
 };
 
 /**