Add support to publish HTML to GH Pages (#103)

* Add typedoc-html option

* add grouping docs support

.eslintignore

@@ -6,3 +6,4 @@ scripts/
 reporter/
 temp/
 examples/
+.tbdocs/

README.md

@@ -157,6 +157,8 @@ docs markdown files in the folder `.tbdocs/docs`.
 
 ```sh
 export GITHUB_REPOSITORY=test-user/test-repo
+export GITHUB_STEP_SUMMARY='../tbdocs-summary.md'
+touch ../tbdocs-summary.md
 
 node scripts/main.js
 

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 { generateTypedocMarkdown } from './typedoc-markdown'
+import { generateTypedoc } from './typedoc'
 
 import { EntryPoint } from '../interfaces'
+import { typedocHtmlGroup } from './typedoc-html-group'
 
 export * from './interfaces'
 
@@ -12,8 +13,27 @@ export * from './interfaces'
 export const generateDocs = async (entryPoint: EntryPoint): Promise<string> => {
   switch (entryPoint.docsGenerator) {
     case 'typedoc-markdown':
-      return generateTypedocMarkdown(entryPoint)
+      return generateTypedoc(entryPoint, true)
+    case 'typedoc-html':
+      return generateTypedoc(entryPoint, false)
     default:
       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/interfaces.ts

@@ -11,4 +11,4 @@
  *
  * @public
  **/
-export type DocsGeneratorType = 'typedoc-markdown'
+export type DocsGeneratorType = 'typedoc-markdown' | 'typedoc-html'

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

@@ -1,6 +1,6 @@
 import path from 'path'
 import { readFileSync, writeFileSync } from 'fs'
-import { Application } from 'typedoc'
+import { Application, TypeDocOptions } from 'typedoc'
 
 import { EntryPoint } from '../interfaces'
 import { loadTsconfigProps, lookupFile } from '../utils'
@@ -17,8 +17,9 @@ declare module 'typedoc' {
 
 const ENTRY_DOCUMENT = 'index.md'
 
-export const generateTypedocMarkdown = async (
-  entryPoint: EntryPoint
+export const generateTypedoc = async (
+  entryPoint: EntryPoint,
+  isMarkdown?: boolean
 ): Promise<string> => {
   console.info('>>> Generating docs...')
 
@@ -33,36 +34,55 @@ export const generateTypedocMarkdown = async (
 
   const { tsconfigFile } = await loadTsconfigProps(entryPoint.projectPath)
 
-  console.info('>>> Typedoc Generator entryPoint', entryPointFile)
-  const generatorApp = await Application.bootstrapWithPlugins({
+  let generatorConfig: Partial<TypeDocOptions> = {
     tsconfig: tsconfigFile,
     entryPoints: [entryPointFile],
     skipErrorChecking: true,
-    plugin: ['typedoc-plugin-markdown'],
-    readme: 'none',
-    entryDocument: ENTRY_DOCUMENT,
     disableSources: true,
-    hidePageTitle: true,
-    hideBreadcrumbs: true,
-    hideInPageTOC: true,
-    githubPages: false
-  })
+    readme: 'none',
+    includeVersion: true
+  }
+
+  if (isMarkdown) {
+    generatorConfig = {
+      ...generatorConfig,
+      plugin: ['typedoc-plugin-markdown'],
+      entryDocument: ENTRY_DOCUMENT,
+      hidePageTitle: true,
+      hideBreadcrumbs: true,
+      hideInPageTOC: true,
+      githubPages: false
+    }
+  }
+
+  console.info(
+    '>>> Typedoc Generator entryPoint',
+    entryPointFile,
+    generatorConfig
+  )
+  const generatorApp = await Application.bootstrapWithPlugins(generatorConfig)
 
   const projectReflection = await generatorApp.convert()
   if (!projectReflection) {
     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
   }
 
-  addTitleToIndexFile(projectReflection.packageName, outputDir)
+  if (isMarkdown) {
+    addTitleToIndexFile(projectReflection.packageName, outputDir)
+  }
 
   return outputDir
 }

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(