add grouping docs support

action.yml

@@ -20,9 +20,9 @@ inputs:
   token:
     description: 'Token used to submit comments summary and open PRs'
     required: false
-  
+
   # to allow opening PRs across different repos we need an authorized bot app
-  # you could also use a user PAT in the above token field, but the generated 
+  # you could also use a user PAT in the above token field, but the generated
   # comments/PRs will be sent from the user
   bot_app_id:
     description: 'Bot app id'
@@ -48,6 +48,11 @@ inputs:
     required: false
     default: 'false'
 
+  group_docs:
+    description: 'Should it group the generated docs files in the `.tbdocs/docs` folder?'
+    required: false
+    default: 'false'
+
   # generated docs params, if you want to open a PR to a different repo with the generated docs
   docs_target_owner_repo:
     description: 'Target owner/repo for the generated docs PR (skips opening a PR if empty)'

src/config.ts

@@ -34,6 +34,8 @@ export const configInputs = {
   failOnError: getInput('fail_on_error') === 'true',
   failOnWarnings: getInput('fail_on_warnings') === 'true',
 
+  groupDocs: getInput('group_docs') === 'true',
+
   docsTargetOwnerRepo: getInput('docs_target_owner_repo'),
   docsTargetBranch: getInput('docs_target_branch'),
   docsTargetPrBaseBranch: getInput('docs_target_pr_base_branch')

src/docs-generator/index.ts

@@ -1,6 +1,7 @@
-import { generateTypedoc } from './typedoc-markdown'
+import { generateTypedoc } from './typedoc'
 
 import { EntryPoint } from '../interfaces'
+import { typedocHtmlGroup } from './typedoc-html-group'
 
 export * from './interfaces'
 
@@ -19,3 +20,20 @@ export const generateDocs = async (entryPoint: EntryPoint): Promise<string> => {
       throw new Error(`Unknown docs generator: ${entryPoint.docsGenerator}`)
   }
 }
+
+/**
+ * Groups all the generated docs into a single docs folder
+ *
+ * @beta
+ */
+export const groupDocs = async (entryPoints: EntryPoint[]): Promise<void> => {
+  const entryPoint = entryPoints[0]
+  switch (entryPoint.docsGenerator) {
+    case 'typedoc-html':
+      return typedocHtmlGroup(entryPoints)
+    default:
+      throw new Error(
+        `Unsupported merging for docs generator: ${entryPoint.docsGenerator}`
+      )
+  }
+}

src/docs-generator/typedoc-html-group.ts

@@ -0,0 +1,40 @@
+import { Application, TypeDocOptions } from 'typedoc'
+
+import { EntryPoint } from '../interfaces'
+
+// Required for the typedoc-plugin-markdown plugin
+declare module 'typedoc' {
+  export interface TypeDocOptionMap {
+    entryDocument: string
+    hidePageTitle: boolean
+    hideBreadcrumbs: boolean
+    hideInPageTOC: boolean
+  }
+}
+
+export const typedocHtmlGroup = async (
+  entryPoints: EntryPoint[]
+): Promise<void> => {
+  console.info('>>> Grouping generated docs...')
+
+  const entryPointsJsons = entryPoints.map(
+    ep => `${ep.generatedDocsPath}/docs.json`
+  )
+
+  const generatorConfig: Partial<TypeDocOptions> = {
+    entryPointStrategy: 'merge',
+    readme: 'none',
+    entryPoints: entryPointsJsons
+  }
+
+  console.info('>>> Typedoc grouping', generatorConfig)
+  const generatorApp = await Application.bootstrapWithPlugins(generatorConfig)
+
+  const projectReflection = await generatorApp.convert()
+  if (!projectReflection) {
+    throw new Error('Failed to group generated docs')
+  }
+
+  console.info('>>> Generating grouped typedoc docs...')
+  await generatorApp.generateDocs(projectReflection, '.tbdocs/docs')
+}

src/docs-generator/typedoc-markdown.ts → src/docs-generator/typedoc.ts

@@ -67,10 +67,14 @@ export const generateTypedoc = async (
     throw new Error('Failed to generate docs')
   }
 
+  console.info('>>> Generating typedoc docs...', { isMarkdown })
   const outputDir = path.join(entryPoint.projectPath, '.tbdocs/docs')
-
   await generatorApp.generateDocs(projectReflection, outputDir)
 
+  console.info('>>> Generating typedoc json...')
+  const outputJson = path.join(outputDir, 'docs.json')
+  await generatorApp.generateJson(projectReflection, outputJson)
+
   // Set project name if not set before
   if (!entryPoint.projectName) {
     entryPoint.projectName = projectReflection.packageName

src/run.ts

@@ -2,7 +2,7 @@ import * as core from '@actions/core'
 
 import { configInputs, getInputEntryPoints } from './config'
 import { runDocsReport, generateReportMarkdown } from './docs-report'
-import { generateDocs } from './docs-generator'
+import { generateDocs, groupDocs } from './docs-generator'
 
 import { getFilesDiffs } from './utils'
 import { handleGithubDocsReport, handleGithubGeneratedDocs } from './github'
@@ -18,7 +18,8 @@ export async function run(): Promise<void> {
       reportChangedScopeOnly,
       docsTargetOwnerRepo,
       failOnError,
-      failOnWarnings
+      failOnWarnings,
+      groupDocs: isGroupDocs
     } = configInputs
 
     const entryPoints = getInputEntryPoints()
@@ -53,6 +54,10 @@ export async function run(): Promise<void> {
       )
     }
 
+    if (isGroupDocs) {
+      await groupDocs(entryPoints)
+    }
+
     const reportMarkdown = await generateReportMarkdown(entryPoints)
 
     await handleGithubDocsReport(