diff --git a/.eslintignore b/.eslintignore index 588cc96..fc83ef4 100644 --- a/.eslintignore +++ b/.eslintignore @@ -6,3 +6,4 @@ scripts/ reporter/ temp/ examples/ +.tbdocs/ diff --git a/README.md b/README.md index 478c593..5f2618f 100644 --- a/README.md +++ b/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 diff --git a/action.yml b/action.yml index ad22f46..5bd7cc9 100644 --- a/action.yml +++ b/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)' diff --git a/badges/coverage.svg b/badges/coverage.svg index f2a4fe8..78eb983 100644 --- a/badges/coverage.svg +++ b/badges/coverage.svg @@ -1 +1 @@ -Coverage: 38.96%Coverage38.96% \ No newline at end of file +Coverage: 40.23%Coverage40.23% \ No newline at end of file diff --git a/src/config.ts b/src/config.ts index 4106269..778d918 100644 --- a/src/config.ts +++ b/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') diff --git a/src/docs-generator/index.ts b/src/docs-generator/index.ts index 844e816..98ec7a6 100644 --- a/src/docs-generator/index.ts +++ b/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 => { 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 => { + const entryPoint = entryPoints[0] + switch (entryPoint.docsGenerator) { + case 'typedoc-html': + return typedocHtmlGroup(entryPoints) + default: + throw new Error( + `Unsupported merging for docs generator: ${entryPoint.docsGenerator}` + ) + } +} diff --git a/src/docs-generator/interfaces.ts b/src/docs-generator/interfaces.ts index c5bd643..a24541c 100644 --- a/src/docs-generator/interfaces.ts +++ b/src/docs-generator/interfaces.ts @@ -11,4 +11,4 @@ * * @public **/ -export type DocsGeneratorType = 'typedoc-markdown' +export type DocsGeneratorType = 'typedoc-markdown' | 'typedoc-html' diff --git a/src/docs-generator/typedoc-html-group.ts b/src/docs-generator/typedoc-html-group.ts new file mode 100644 index 0000000..1a1b200 --- /dev/null +++ b/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 => { + console.info('>>> Grouping generated docs...') + + const entryPointsJsons = entryPoints.map( + ep => `${ep.generatedDocsPath}/docs.json` + ) + + const generatorConfig: Partial = { + 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') +} diff --git a/src/docs-generator/typedoc-markdown.ts b/src/docs-generator/typedoc.ts similarity index 65% rename from src/docs-generator/typedoc-markdown.ts rename to src/docs-generator/typedoc.ts index 90d16a0..472b7c6 100644 --- a/src/docs-generator/typedoc-markdown.ts +++ b/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 => { 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 = { 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 } diff --git a/src/run.ts b/src/run.ts index 11177b8..65b50a5 100644 --- a/src/run.ts +++ b/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 { reportChangedScopeOnly, docsTargetOwnerRepo, failOnError, - failOnWarnings + failOnWarnings, + groupDocs: isGroupDocs } = configInputs const entryPoints = getInputEntryPoints() @@ -53,6 +54,10 @@ export async function run(): Promise { ) } + if (isGroupDocs) { + await groupDocs(entryPoints) + } + const reportMarkdown = await generateReportMarkdown(entryPoints) await handleGithubDocsReport(