diff --git a/README.md b/README.md index a88fa3c..be2ad44 100644 --- a/README.md +++ b/README.md @@ -29,14 +29,31 @@ var vueDocs = require('vue-docgen-api') var componentInfo = vueDocs.parse(filePath) ``` -or with typescript/es6 +or with typescript ```ts import { parse } from 'vue-docgen-api' -var componentInfo = parse(filePath) +var componentInfo = parse(filePath); +var componentInfo = vueDocs.parse(filePath, { + alias: {"@assets": path.resolve(__dirname, "src/assets")}, + resolve: [path.resolve(__dirname, "src")], + addScriptHandler: [function( + documentation: Documentation, + componentDefinition: NodePath, + astPath: bt.File, + opt: ParseOptions){ + // handle custom code in script + }], + addTemplateHandler: [function( + documentation: Documentation, + templateAst: ASTElement, + options: TemplateParserOptions){ + // handle custom directives here + }] +}) ``` -### parse(filePath) +### parse(filePath:string, options?: DocGenOptions) | Parameter | Type | Description | | --------- | ------ | ------------- | diff --git a/src/main.ts b/src/main.ts index 29f65f1..68d5848 100755 --- a/src/main.ts +++ b/src/main.ts @@ -1,20 +1,33 @@ import { ComponentDoc, Documentation } from './Documentation' -import { parseFile, parseSource as parseSourceLocal } from './parse' +import { DocGenOptions, parseFile, ParseOptions, parseSource as parseSourceLocal } from './parse' +export { ScriptHandler, TemplateHandler } from './parse' +export { ComponentDoc, DocGenOptions, ParseOptions, Documentation } -export { ComponentDoc } - -export function parse(filePath: string, aliases?: { [alias: string]: string }): ComponentDoc { +export function parse( + filePath: string, + opts?: DocGenOptions | { [alias: string]: string }, +): ComponentDoc { const doc = new Documentation() - parseFile(doc, { filePath, aliases }) + const options: ParseOptions = isOptionsObject(opts) + ? { ...opts, filePath } + : { filePath, alias: opts } + parseFile(doc, options) return doc.toObject() } export function parseSource( source: string, filePath: string, - aliases?: { [alias: string]: string }, + opts?: DocGenOptions | { [alias: string]: string }, ): ComponentDoc { const doc = new Documentation() - parseSourceLocal(doc, source, { filePath, aliases }) + const options: ParseOptions = isOptionsObject(opts) + ? { ...opts, filePath } + : { filePath, alias: opts } + parseSourceLocal(doc, source, options) return doc.toObject() } + +function isOptionsObject(opts: any): opts is DocGenOptions { + return !!opts && !!opts.alias +} diff --git a/src/parse-script.ts b/src/parse-script.ts index ba8b420..c931094 100644 --- a/src/parse-script.ts +++ b/src/parse-script.ts @@ -13,7 +13,7 @@ import { ParseOptions } from './parse' const ERROR_MISSING_DEFINITION = 'No suitable component definition found' -type Handler = ( +export type Handler = ( doc: Documentation, componentDefinition: NodePath, ast: bt.File, diff --git a/src/parse.ts b/src/parse.ts index e7be496..897d151 100755 --- a/src/parse.ts +++ b/src/parse.ts @@ -2,19 +2,47 @@ import * as fs from 'fs' import * as path from 'path' import { parseComponent, SFCDescriptor } from 'vue-template-compiler' import { Documentation } from './Documentation' -import parseScript from './parse-script' -import parseTemplate from './parse-template' -import handlers from './script-handlers' +import parseScript, { Handler as ScriptHandler } from './parse-script' +import parseTemplate, { Handler as TemplateHandler } from './parse-template' +import scriptHandlers from './script-handlers' import templateHandlers from './template-handlers' import cacher from './utils/cacher' const ERROR_EMPTY_DOCUMENT = 'The passed source is empty' -export interface ParseOptions { +export { ScriptHandler, TemplateHandler } + +export interface ParseOptions extends DocGenOptions { filePath: string + /** + * In what language is the component written + * @default undefined - let the system decide + */ lang?: 'ts' | 'js' +} + +export interface DocGenOptions { + /** + * Which exported variables should be looked at + * @default undefined - means treat all dependencies + */ nameFilter?: string[] - aliases?: { [alias: string]: string } + /** + * What alias should be replaced in requires and imports + */ + alias?: { [alias: string]: string } + /** + * What directories should be searched when resolving modules + */ + modules?: string[] + /** + * Handlers that will be added at the end of the script analysis + */ + addScriptHandlers?: ScriptHandler[] + /** + * Handlers that will be added at the end of the template analysis + */ + addTemplateHandlers?: TemplateHandler[] } /** @@ -50,7 +78,13 @@ export function parseSource(documentation: Documentation, source: string, opt: P // get slots and props from template if (parts && parts.template) { - parseTemplate(parts.template, documentation, templateHandlers, opt.filePath) + const addTemplateHandlers: TemplateHandler[] = opt.addTemplateHandlers || [] + parseTemplate( + parts.template, + documentation, + [...templateHandlers, ...addTemplateHandlers], + opt.filePath, + ) } const scriptSource = parts ? (parts.script ? parts.script.content : undefined) : source @@ -60,8 +94,8 @@ export function parseSource(documentation: Documentation, source: string, opt: P /\.tsx?$/i.test(path.extname(opt.filePath)) ? 'ts' : 'js' - - parseScript(scriptSource, documentation, handlers, opt) + const addScriptHandlers: ScriptHandler[] = opt.addScriptHandlers || [] + parseScript(scriptSource, documentation, [...scriptHandlers, ...addScriptHandlers], opt) } if (!documentation.get('displayName')) { diff --git a/src/script-handlers/extendsHandler.ts b/src/script-handlers/extendsHandler.ts index 40c451d..7497df9 100644 --- a/src/script-handlers/extendsHandler.ts +++ b/src/script-handlers/extendsHandler.ts @@ -31,7 +31,7 @@ export default function extendsHandler( const originalDirName = path.dirname(opt.filePath) - const pathResolver = makePathResolver(originalDirName, opt.aliases) + const pathResolver = makePathResolver(originalDirName, opt.alias) resolveImmediatelyExportedRequire(pathResolver, extendsFilePath) diff --git a/src/script-handlers/mixinsHandler.ts b/src/script-handlers/mixinsHandler.ts index ceb2462..83dc2e3 100644 --- a/src/script-handlers/mixinsHandler.ts +++ b/src/script-handlers/mixinsHandler.ts @@ -21,7 +21,7 @@ export default function mixinsHandler( ) { const originalDirName = path.dirname(opt.filePath) - const pathResolver = makePathResolver(originalDirName, opt.aliases) + const pathResolver = makePathResolver(originalDirName, opt.alias) // filter only mixins const mixinVariableNames = getMixinsVariableNames(componentDefinition) diff --git a/src/utils/makePathResolver.ts b/src/utils/makePathResolver.ts index 41592a6..328f44d 100644 --- a/src/utils/makePathResolver.ts +++ b/src/utils/makePathResolver.ts @@ -4,7 +4,11 @@ import resolvePathFrom from '../utils/resolvePathFrom' export default function makePathResolver( refDirName: string, aliases?: { [alias: string]: string }, + modules?: string[], ): (filePath: string, originalDirNameOverride?: string) => string { return (filePath: string, originalDirNameOverride?: string): string => - resolvePathFrom(resolveAliases(filePath, aliases || {}), originalDirNameOverride || refDirName) + resolvePathFrom(resolveAliases(filePath, aliases || {}), [ + originalDirNameOverride || refDirName, + ...(modules || []), + ]) } diff --git a/src/utils/resolvePathFrom.ts b/src/utils/resolvePathFrom.ts index 8470794..4adcab8 100644 --- a/src/utils/resolvePathFrom.ts +++ b/src/utils/resolvePathFrom.ts @@ -1,12 +1,12 @@ const SUFFIXES = ['', '.js', '.ts', '.vue', '/index.js', '/index.ts'] -export default function resolvePathFrom(path: string, from: string): string { +export default function resolvePathFrom(path: string, from: string[]): string { let finalPath = '' SUFFIXES.forEach(s => { if (!finalPath.length) { try { finalPath = require.resolve(`${path}${s}`, { - paths: [from], + paths: from, }) } catch (e) { // eat the error diff --git a/tests/components/mixin-resolved/button.vue b/tests/components/mixin-resolved/button.vue index 3955931..cb2cab8 100644 --- a/tests/components/mixin-resolved/button.vue +++ b/tests/components/mixin-resolved/button.vue @@ -8,6 +8,7 @@