-
Notifications
You must be signed in to change notification settings - Fork 182
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: Added support for TypDoc
watch option
- Loading branch information
Showing
7 changed files
with
196 additions
and
94 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,52 @@ | ||
| import { reflectionTitle } from 'typedoc-plugin-markdown/dist/resources/helpers/reflection-title'; | ||
| import { Component } from 'typedoc/dist/lib/converter/components'; | ||
| import { RendererComponent } from 'typedoc/dist/lib/output/components'; | ||
| import { PageEvent } from 'typedoc/dist/lib/output/events'; | ||
|
|
||
| @Component({ name: 'front-matter' }) | ||
| export class FrontMatterComponent extends RendererComponent { | ||
| initialize() { | ||
| super.initialize(); | ||
| this.listenTo(this.application.renderer, { | ||
| [PageEvent.END]: this.onPageEnd, | ||
| }); | ||
| } | ||
| onPageEnd(page: PageEvent) { | ||
| if (page.contents) { | ||
| page.contents = page.contents | ||
| .replace(/^/, this.getYamlString(this.getYamlItems(page)) + '\n\n') | ||
| .replace(/[\r\n]{3,}/g, '\n\n'); | ||
| } | ||
| } | ||
|
|
||
| getYamlString(yamlItems: { [key: string]: string | number | boolean }) { | ||
| const yaml = `--- | ||
| ${Object.entries(yamlItems) | ||
| .map( | ||
| ([key, value]) => | ||
| `${key}: ${ | ||
| typeof value === 'string' ? `"${this.escapeYAMLString(value)}"` : value | ||
| }`, | ||
| ) | ||
| .join('\n')} | ||
| ---`; | ||
| return yaml; | ||
| } | ||
|
|
||
| getYamlItems(page: PageEvent): any { | ||
| const pageTitle = this.getTitle(page); | ||
|
|
||
| return { | ||
| title: pageTitle, | ||
| }; | ||
| } | ||
|
|
||
| getTitle(page: PageEvent) { | ||
| return reflectionTitle.call(page, false); | ||
| } | ||
|
|
||
| // prettier-ignore | ||
| escapeYAMLString(str: string) { | ||
| return str.replace(/([^\\])'/g, '$1\\\'').replace(/\"/g, ''); | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,80 @@ | ||
| import * as path from 'path'; | ||
|
|
||
| import { | ||
| Application, | ||
| MixedDeclarationOption, | ||
| ParameterType, | ||
| TSConfigReader, | ||
| TypeDocReader, | ||
| } from 'typedoc'; | ||
|
|
||
| import { PluginOptions, SidebarOptions } from './types'; | ||
|
|
||
| /** | ||
| * Default plugin options | ||
| */ | ||
| const DEFAULT_PLUGIN_OPTIONS: PluginOptions = { | ||
| out: 'api', | ||
| hideBreadcrumbs: true, | ||
| plugin: ['typedoc-plugin-markdown'], | ||
| sidebar: { | ||
| parentCategory: 'none', | ||
| fullNames: false, | ||
| sidebarFile: 'typedoc-sidebar.js', | ||
| sidebarPath: '', | ||
| }, | ||
| watch: false, | ||
| }; | ||
|
|
||
| /** | ||
| * Merge default with user options | ||
| * @param opts | ||
| */ | ||
| export const getOptions = (opts: Partial<PluginOptions>): PluginOptions => { | ||
| // base options | ||
| let options = { | ||
| ...DEFAULT_PLUGIN_OPTIONS, | ||
| ...opts, | ||
| }; | ||
| // sidebar | ||
| if (opts.sidebar === null) { | ||
| options = { ...options, sidebar: null }; | ||
| } else { | ||
| const sidebar = { | ||
| ...DEFAULT_PLUGIN_OPTIONS.sidebar, | ||
| ...opts.sidebar, | ||
| } as SidebarOptions; | ||
| options = { | ||
| ...options, | ||
| sidebar: { | ||
| ...sidebar, | ||
| sidebarPath: path.resolve(sidebar.sidebarFile), | ||
| }, | ||
| }; | ||
| } | ||
| // plugin | ||
| if (opts.plugin) { | ||
| options = { | ||
| ...options, | ||
| plugin: [...DEFAULT_PLUGIN_OPTIONS.plugin, ...opts.plugin], | ||
| }; | ||
| } | ||
| // additional | ||
| options = { | ||
| ...options, | ||
| // siteDir, | ||
| // outputDirectory: path.resolve(siteDir, options.docsRoot, options.out), | ||
| }; | ||
| return options; | ||
| }; | ||
|
|
||
| export const addOptions = (app: Application) => { | ||
| // configure deault typedoc options | ||
| app.options.addReader(new TypeDocReader()); | ||
| app.options.addReader(new TSConfigReader()); | ||
|
|
||
| app.options.addDeclaration({ | ||
| name: 'sidebar', | ||
| type: ParameterType.Mixed, | ||
| } as MixedDeclarationOption); | ||
| }; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,115 +1,83 @@ | ||
| import { | ||
| Application, | ||
| ProjectReflection, | ||
| TSConfigReader, | ||
| TypeDocOptions, | ||
| TypeDocReader, | ||
| } from 'typedoc'; | ||
| import { FrontMatterComponent } from 'typedoc-plugin-markdown/dist/components/front-matter'; | ||
| import { Application, ProjectReflection } from 'typedoc'; | ||
|
|
||
| import { FrontMatterComponent } from './front-matter'; | ||
| import { addOptions, getOptions } from './options'; | ||
| import { getSidebarJson } from './sidebar'; | ||
| import { PluginOptions } from './types'; | ||
|
|
||
| const DEFAULT_PLUGIN_OPTIONS: PluginOptions = { | ||
| out: 'api', | ||
| sidebar: { | ||
| parentCategory: 'none', | ||
| fullNames: false, | ||
| }, | ||
| }; | ||
|
|
||
| const app = new Application(); | ||
|
|
||
| let done = false; | ||
| let app: Application; | ||
| let project: ProjectReflection | undefined; | ||
| const done = false; | ||
|
|
||
| export const typedocPlugin = (opts: PluginOptions, ctx: any) => { | ||
| const sourceDir = ctx.sourceDir; | ||
|
|
||
| const options = { ...DEFAULT_PLUGIN_OPTIONS, ...opts }; | ||
|
|
||
| const outFolder = options.out ? options.out : 'api'; | ||
| const out = sourceDir + '/' + outFolder; | ||
| const sidebar = options.sidebar; | ||
|
|
||
| let project: ProjectReflection | undefined; | ||
|
|
||
| // don't re-compile on dev server | ||
| // merge default plugin options with user options | ||
| const options = getOptions(opts); | ||
|
|
||
| return { | ||
| name: 'vuepress-plugin-typedoc', | ||
| async ready() { | ||
| // TypeDoc options | ||
| const vuepressOptions = Object.keys(options).reduce((option, key) => { | ||
| if ( | ||
| ![...['id'], ...Object.keys(DEFAULT_PLUGIN_OPTIONS)].includes(key) | ||
| ) { | ||
| option[key] = options[key]; | ||
| } | ||
| return option; | ||
| }, {}); | ||
| if (!done) { | ||
| app = new Application(); | ||
|
|
||
| app.options.addReader(new TypeDocReader()); | ||
| app.options.addReader(new TSConfigReader()); | ||
| const sourceDir = ctx.sourceDir; | ||
| const outputDirectory = sourceDir + '/' + options.out; | ||
|
|
||
| // bootstrap | ||
| app.bootstrap({ | ||
| // filtered vuepress options | ||
| ...vuepressOptions, | ||
| hideInPageTOC: true, | ||
| hideBreadcrumbs: true, | ||
| // TypeDoc plugins | ||
| plugin: [ | ||
| ...['typedoc-plugin-markdown'], | ||
| ...(opts.plugin | ||
| ? opts.plugin.filter((name) => name !== 'typedoc-plugin-markdown') | ||
| : []), | ||
| ], | ||
| } as Partial<TypeDocOptions>); | ||
| // add plugin options | ||
| addOptions(app); | ||
|
|
||
| app.renderer.addComponent( | ||
| 'frontmatter', | ||
| new FrontMatterComponent(app.renderer), | ||
| ); | ||
| // bootstrap typedoc app | ||
| app.bootstrap(options); | ||
|
|
||
| project = app.convert(); | ||
| // add frontmatter component to typedoc renderer | ||
| app.renderer.addComponent('fm', new FrontMatterComponent(app.renderer)); | ||
|
|
||
| // if project is undefined typedoc has a problem - error logging will be supplied by typedoc. | ||
| if (!project) { | ||
| done = true; | ||
| return; | ||
| } | ||
| // add sidebar component to typedoc renderer | ||
| /*if (options.sidebar) { | ||
| app.renderer.addComponent( | ||
| 'sidebar', | ||
| new SidebarComponent(app.renderer), | ||
| ); | ||
| }*/ | ||
|
|
||
| await app.generateDocs(project, out); | ||
| project = app.convert(); | ||
|
|
||
| return; | ||
| // if project is undefined typedoc has a problem - error logging will be supplied by typedoc. | ||
| if (!project) { | ||
| return; | ||
| } | ||
|
|
||
| // generate docs | ||
| await app.generateDocs(project, outputDirectory); | ||
|
|
||
| // watch pp | ||
| if (options.watch) { | ||
| app.convertAndWatch(async (project) => { | ||
| await app.generateDocs(project, outputDirectory); | ||
| }); | ||
| } | ||
| } | ||
| }, | ||
| async enhanceAppFiles() { | ||
| if (done || !sidebar) { | ||
| if (done || !options.sidebar) { | ||
| return; | ||
| } | ||
|
|
||
| const theme = app.renderer.theme as any; | ||
|
|
||
| const navigation = theme.getNavigation(project); | ||
|
|
||
| return { | ||
| name: 'typedoc-sidebar', | ||
| content: `export default ({ siteData, options }) => { | ||
| siteData.themeConfig.sidebarDepth = 2; | ||
| siteData.themeConfig.sidebarDepth = 0; | ||
| siteData.themeConfig.sidebar = Object.assign({},siteData.themeConfig.sidebar,${JSON.stringify( | ||
| { | ||
| [`/${outFolder}/`]: getSidebarJson( | ||
| [`/${options.out}/`]: getSidebarJson( | ||
| navigation, | ||
| outFolder, | ||
| sidebar, | ||
| options.out, | ||
| options.sidebar, | ||
| ), | ||
| }, | ||
| )}); | ||
| }`, | ||
| }; | ||
| }, | ||
|
|
||
| afterDevServer() { | ||
| done = true; | ||
| }, | ||
| }; | ||
| }; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters