vue-docgen-api
Advanced tools
Comparing version 4.45.0 to 4.46.0
112
package.json
| { | ||
| "name": "vue-docgen-api", | ||
| "version": "4.45.0", | ||
| "description": "Toolbox to extract information from Vue component files for documentation generation purposes.", | ||
| "homepage": "https://vue-styleguidist.github.io", | ||
| "main": "dist/main.js", | ||
| "types": "dist/main.d.ts", | ||
| "scripts": { | ||
| "compile": "tsc -p ./tsconfig.build.json", | ||
| "compile:watch": "pnpm run compile --watch" | ||
| }, | ||
| "files": [ | ||
| "dist" | ||
| ], | ||
| "repository": { | ||
| "type": "git", | ||
| "url": "https://github.com/vue-styleguidist/vue-styleguidist.git", | ||
| "directory": "packages/vue-docgen-api" | ||
| }, | ||
| "bugs": { | ||
| "url": "https://github.com/vue-styleguidist/vue-styleguidist/issues" | ||
| }, | ||
| "keywords": [ | ||
| "vue", | ||
| "documentation-generation", | ||
| "jsdoc", | ||
| "parse" | ||
| ], | ||
| "author": "elevatebart", | ||
| "license": "MIT", | ||
| "dependencies": { | ||
| "@babel/parser": "^7.13.12", | ||
| "@babel/types": "^7.13.12", | ||
| "@vue/compiler-dom": "^3.2.0", | ||
| "@vue/compiler-sfc": "^3.2.0", | ||
| "ast-types": "0.14.2", | ||
| "hash-sum": "^1.0.2", | ||
| "lru-cache": "^4.1.5", | ||
| "pug": "^3.0.2", | ||
| "recast": "0.20.5", | ||
| "ts-map": "^1.0.3", | ||
| "vue-inbrowser-compiler-utils": "^4.44.23" | ||
| }, | ||
| "devDependencies": { | ||
| "@test-vue-docgen/mixins": "^4.44.15", | ||
| "@types/dedent": "0.7.0", | ||
| "@types/pug": "2.0.6", | ||
| "dedent": "0.7.0", | ||
| "globby": "10.0.2", | ||
| "vue": "2.6.14", | ||
| "vue-class-component": "7.2.6", | ||
| "vue-clickaway": "2.2.2", | ||
| "vue-property-decorator": "7.3.0", | ||
| "vuetify": "2.6.3" | ||
| }, | ||
| "gitHead": "a668a816ea87559cf3cd89da5bf35c257c7da743" | ||
| } | ||
| "name": "vue-docgen-api", | ||
| "version": "4.46.0", | ||
| "description": "Toolbox to extract information from Vue component files for documentation generation purposes.", | ||
| "homepage": "https://vue-styleguidist.github.io", | ||
| "main": "dist/main.js", | ||
| "types": "dist/main.d.ts", | ||
| "files": [ | ||
| "dist" | ||
| ], | ||
| "repository": { | ||
| "type": "git", | ||
| "url": "https://github.com/vue-styleguidist/vue-styleguidist.git", | ||
| "directory": "packages/vue-docgen-api" | ||
| }, | ||
| "bugs": { | ||
| "url": "https://github.com/vue-styleguidist/vue-styleguidist/issues" | ||
| }, | ||
| "keywords": [ | ||
| "vue", | ||
| "documentation-generation", | ||
| "jsdoc", | ||
| "parse" | ||
| ], | ||
| "author": "elevatebart", | ||
| "license": "MIT", | ||
| "dependencies": { | ||
| "@babel/parser": "^7.13.12", | ||
| "@babel/types": "^7.13.12", | ||
| "@vue/compiler-dom": "^3.2.0", | ||
| "@vue/compiler-sfc": "^3.2.0", | ||
| "ast-types": "0.14.2", | ||
| "hash-sum": "^1.0.2", | ||
| "lru-cache": "^4.1.5", | ||
| "pug": "^3.0.2", | ||
| "recast": "0.20.5", | ||
| "ts-map": "^1.0.3", | ||
| "vue-inbrowser-compiler-utils": "^4.44.23" | ||
| }, | ||
| "devDependencies": { | ||
| "@test-vue-docgen/mixins": "^4.44.15", | ||
| "@types/dedent": "0.7.0", | ||
| "@types/pug": "2.0.6", | ||
| "dedent": "0.7.0", | ||
| "globby": "10.0.2", | ||
| "vue": "2.6.14", | ||
| "vue-class-component": "7.2.6", | ||
| "vue-clickaway": "2.2.2", | ||
| "vue-property-decorator": "7.3.0", | ||
| "vuetify": "2.6.3" | ||
| }, | ||
| "scripts": { | ||
| "compile": "tsc -p ./tsconfig.build.json", | ||
| "compile:watch": "pnpm run compile --watch" | ||
| }, | ||
| "readme": "# vue-docgen-api\n\n[Online Documentation](https://vue-styleguidist.github.io/docs/Docgen.html)\n\n`vue-docgen-api` is a toolbox to help extracting information from [Vue](https://vuejs.org/) components, and generate documentation from it.\n\nUse [@babel/parser](https://babeljs.io/docs/en/babel-parser) to parse the code and analyze the contents of the component extracting methods, props events and slots. The output is a JavaScript object.\n\n## Install\n\nInstall the module directly from npm:\n\n```sh\nnpm install vue-docgen-api --save-dev\n```\n\n## API\n\nThe tool can be used programmatically to extract component information and customize the extraction process:\n\n```js\nvar vueDocs = require('vue-docgen-api')\nvar componentInfo\nvueDocs.parse(filePath).then(ci => {\n componentInfo = ci\n})\n```\n\nor with typescript\n\n```ts\nimport { parse } from 'vue-docgen-api'\n\nasync function parseMyComponent(filePath: string) {\n var componentInfoSimple = await parse(filePath)\n var componentInfoConfigured = await parse(filePath, {\n alias: { '@assets': path.resolve(__dirname, 'src/assets') },\n modules: [path.resolve(__dirname, 'src')],\n addScriptHandlers: [\n function(\n documentation: Documentation,\n componentDefinition: NodePath,\n astPath: bt.File,\n opt: ParseOptions\n ) {\n // handle custom code in script\n }\n ],\n addTemplateHandlers: [\n function(\n documentation: Documentation,\n templateAst: ASTElement,\n options: TemplateParserOptions\n ) {\n // handle custom directives here\n }\n ],\n preScriptHandlers: [\n function(\n documentation: Documentation,\n componentDefinition: NodePath,\n astPath: bt.File,\n opt: ParseOptions\n ) {\n // replaces handlers run before the scriptHandlers\n }\n ],\n scriptHandlers: [\n function(\n documentation: Documentation,\n componentDefinition: NodePath,\n astPath: bt.File,\n opt: ParseOptions\n ) {\n // replaces all the scriptHandlers\n }\n ],\n templateHandlers: [\n function(\n documentation: Documentation,\n templateAst: ASTElement,\n options: TemplateParserOptions\n ) {\n // replaces all the templateHandlers\n }\n ],\n validExtends: (fullFilePath: string) =>\n /[\\\\/]@my-component-library[\\\\/]/.test(fullFilePath) ||\n !/[\\\\/]node_modules[\\\\/]/.test(fullFilePath)\n jsx: true,\n nameFilter: ['MyComponent']\n })\n}\n```\n\n### `parse()` vs `parseMulti()`\n\nThe API exports two asynchronous functions `parse` and `parseMulti`. The two functions take the same set of parameters. `parse` returns a pure `ComponentDoc` whereas `parseMulti` returns an array of `ComponentDoc`\n\nWhen using only SFC or components that are the only one in their components, this function returns a `ComponentDoc` object. Using `parse` in most cases is simpler.\n\nIf you are creating a library and your goal is to have it as generic as possible, it might be a good idea to use `parseMulti`. In some cases, developer choose to have **more than one component** exported by a file, which make `parse` throw an error.\n\n### Prototypes\n\n```ts\nparse(filePath: string, options: DocGenOptions): Promise<ComponentDoc>;\nparseSource(source: string, filePath: string, opts?: DocGenOptions): Promise<ComponentDoc>;\nparseMulti(filePath: string, options: DocGenOptions): Promise<ComponentDoc[]>;\n```\n\n### options `DocGenOptions`\n\n#### `alias`\n\nThis is a mirror to the [wepbpack alias](https://webpack.js.org/configuration/resolve/#resolvealias) options. If you are using [alias in Webpack](https://webpack.js.org/configuration/resolve/#resolvealias) or paths in TypeScript, you should reflect this here.\n\nKeep in mind aliases are not resolved adopting the same implementation as webpack, but as simple path replacement. Aliases are resolved as soon as they match in the file path, bailing out of further tests. This means the order in which aliases are defined matters. E.g. an alias `@templates` mapped to `styleguide/templates/` should be defined earlier than the alias `@` (mapped to `src` ) to avoid `@templates/component` being resolved as `srctemplates/component` instead of `styleguide/templates/component`.\n\n#### `modules`\n\n`modules` mirrors the [webpack option](https://webpack.js.org/configuration/resolve/#resolvemodules) too. If you have it in webpack or use `baseDir` in your tsconfig.json, you should probably see how this one works.\n\n#### `addScriptHandlers` and `addTemplateHandlers`\n\nThe custom additional handlers allow you to add custom handlers to the parser. A handler can navigate and see custom objects that the standard parser would ignore.\n\n#### `preScriptHandlers`, `scriptHandlers` and `templateHandlers`\n\nReplaces all of the handlers by those specified. If each of those 3 `handlers` are set to [], the library will only parse the given component. It will not run any standard handlers anymore.\n\n> **NOTE:** Standard handlers are available as namespaces. Import and use them this way:\n>\n> ```js\n> import {\n> parse,\n> ScriptHandlers,\n> TemplateHandlers\n> } from 'vue-docgen-api'\n>\n> parse('myComp', {\n> scriptHandlers: [ScriptHandlers.componentHandler],\n> templateHandlers: [TemplateHandlers.slotHandler]\n> })\n> ```\n\n#### `validExtend`\n\nFunction - Returns true if an extended component should be parsed by docgen.\n\nExample: `filePath => !/node_modules/.text(filePath)`\n\n> **NOTE1:** If docgen fails to parse the targeted component, it will log a warning. This warning does not make the documentation fail.\n\n> **NOTE2:** If you allow all of `node_modules` to try to be parsed, you might kill performance. Use responsibly.\n\n#### `jsx`\n\nDoes your component contain JSX? By default, this is set to false to avoid conflicts with the <> syntax from TypeScript.\n\nIf it does, set this flag to true.\n\n#### `nameFilter`\n\nIf a file exports multiple components and you only want one, use this option to filter the named exports.\n\nIt is noticeably useful when browsing through extended components and mixins. If left blank (undefined), will look at all exports\n\n## Using JSDoc tags\n\nYou can use JSDoc tags when documenting components, props and methods.\n\n## Props\n\n```js\nexport default {\n props: {\n /**\n * Color of the button.\n */\n color: {\n type: String,\n default: '#FCC'\n },\n /**\n * initial value to be passed but undocumented\n * @ignore\n */\n initialvalue: {\n type: Number,\n default: 0\n },\n /**\n * The size of the button allows only some values\n * @values small, medium, large\n */\n size: {\n default: 'normal'\n }\n }\n}\n```\n\n## Events\n\n```js\nexport default {\n methods: {\n emitSuccess() {\n /**\n * Success event.\n *\n * @event success\n * @property {string} content content of the first prop passed to the event\n * @property {object} example the demo example\n */\n this.$emit('success', content, {\n demo: 'example'\n })\n }\n }\n}\n```\n\n## Slots\n\n```html\n<template>\n <div>\n <!-- @slot Use this slot header -->\n <slot name=\"header\"></slot>\n\n <!--\n @slot Modal footer\n @binding item an item passed to the footer\n\t\t-->\n <slot name=\"footer\" :item=\"item\" />\n </div>\n</template>\n```\n\n## Full Example\n\nFor the following component\n\n```vue\n<template>\n <div>\n <!-- @slot Use this slot header -->\n <slot name=\"header\"></slot>\n\n <table class=\"grid\">\n <!-- -->\n </table>\n\n <!--\n @slot Modal footer\n @binding item an item passed to the footer\n\t\t-->\n <slot name=\"footer\" :item=\"item\" />\n </div>\n</template>\n\n<script>\nimport { text } from './utils'\n\n/**\n * This is an example of creating a reusable grid component and using it with external data.\n * @version 1.0.5\n * @author [Rafael](https://github.com/rafaesc92)\n * @since Version 1.0.1\n */\nexport default {\n name: 'grid',\n props: {\n /**\n * object/array defaults should be returned from a factory function\n * @version 1.0.5\n * @since Version 1.0.1\n * @see See [Wikipedia](https://en.wikipedia.org/wiki/Web_colors#HTML_color_names) for a list of color names\n * @link See [Wikipedia](https://en.wikipedia.org/wiki/Web_colors#HTML_color_names) for a list of color names\n */\n msg: {\n type: [String, Number],\n default: text\n },\n /**\n * Model example\n * @model\n */\n value: {\n type: String\n },\n /**\n * describe data\n * @version 1.0.5\n */\n data: [Array],\n /**\n * get columns list\n */\n columns: [Array],\n /**\n * filter key\n * @ignore\n */\n filterKey: {\n type: String,\n default: 'example'\n }\n },\n data() {\n var sortOrders = {}\n this.columns.forEach(function (key) {\n sortOrders[key] = 1\n })\n return {\n sortKey: '',\n sortOrders: sortOrders\n }\n },\n computed: {\n filteredData: function () {\n var sortKey = this.sortKey\n var filterKey = this.filterKey && this.filterKey.toLowerCase()\n var order = this.sortOrders[sortKey] || 1\n var data = this.data\n if (filterKey) {\n data = data.filter(function (row) {\n return Object.keys(row).some(function (key) {\n return (\n String(row[key]).toLowerCase().indexOf(filterKey) > -1\n )\n })\n })\n }\n if (sortKey) {\n data = data.slice().sort(function (a, b) {\n a = a[sortKey]\n b = b[sortKey]\n return (a === b ? 0 : a > b ? 1 : -1) * order\n })\n }\n return data\n }\n },\n filters: {\n capitalize: function (str) {\n return str.charAt(0).toUpperCase() + str.slice(1)\n }\n },\n methods: {\n /**\n * Sets the order\n *\n * @public\n * @version 1.0.5\n * @since Version 1.0.1\n * @param {string} key Key to order\n * @returns {string} Test\n */\n sortBy: function (key) {\n this.sortKey = key\n this.sortOrders[key] = this.sortOrders[key] * -1\n\n /**\n * Success event.\n *\n * @event success\n * @type {object}\n */\n this.$emit('success', {\n demo: 'example'\n })\n },\n\n hiddenMethod: function () {}\n }\n}\n</script>\n```\n\nwe are getting this output:\n\n```js\nconst componentDoc = {\n displayName: 'grid',\n description:\n 'This is an example of creating a reusable grid component and using it with external data.',\n tags: {\n version: [\n {\n description: '1.0.5',\n title: 'version'\n }\n ],\n author: [\n {\n description: '[Rafael](https://github.com/rafaesc92)',\n title: 'author'\n }\n ],\n since: [\n {\n description: 'Version 1.0.1',\n title: 'since'\n }\n ]\n },\n exportName: 'default',\n props: [\n {\n description:\n 'object/array defaults should be returned from a factory function',\n tags: {\n version: [\n {\n description: '1.0.5',\n title: 'version'\n }\n ],\n since: [\n {\n description: 'Version 1.0.1',\n title: 'since'\n }\n ],\n see: [\n {\n description:\n 'See [Wikipedia](https://en.wikipedia.org/wiki/Web_colors#HTML_color_names) for a list of color names',\n title: 'see'\n }\n ],\n link: [\n {\n description:\n 'See [Wikipedia](https://en.wikipedia.org/wiki/Web_colors#HTML_color_names) for a list of color names',\n title: 'link'\n }\n ]\n },\n name: 'msg',\n type: {\n name: 'string|number'\n },\n defaultValue: {\n func: false,\n value: 'text'\n }\n },\n {\n description: 'Model example',\n tags: {\n model: [\n {\n description: true,\n title: 'model'\n }\n ]\n },\n name: 'v-model',\n type: {\n name: 'string'\n }\n },\n {\n description: 'describe data',\n tags: {\n version: [\n {\n description: '1.0.5',\n title: 'version'\n }\n ]\n },\n name: 'data',\n type: {\n name: 'array'\n }\n },\n {\n description: 'get columns list',\n tags: {},\n name: 'columns',\n type: {\n name: 'array'\n }\n },\n {\n description: 'filter key',\n tags: {\n ignore: [\n {\n description: true,\n title: 'ignore'\n }\n ]\n },\n name: 'filterKey',\n type: {\n name: 'string'\n },\n defaultValue: {\n func: false,\n value: \"'example'\"\n }\n }\n ],\n events: [\n {\n name: 'success',\n description: 'Success event.',\n type: {\n names: ['object']\n }\n }\n ],\n methods: [\n {\n name: 'sortBy',\n modifiers: [],\n description: 'Sets the order',\n tags: {\n access: [\n {\n description: 'public',\n title: 'access'\n }\n ],\n version: [\n {\n description: '1.0.5',\n title: 'version'\n }\n ],\n since: [\n {\n description: 'Version 1.0.1',\n title: 'since'\n }\n ],\n params: [\n {\n title: 'param',\n type: {\n name: 'string'\n },\n name: 'key',\n description: 'Key to order'\n }\n ],\n returns: [\n {\n title: 'returns',\n type: {\n name: 'string'\n },\n description: 'Test'\n }\n ]\n },\n params: [\n {\n name: 'key',\n type: {\n name: 'string'\n },\n description: 'Key to order'\n }\n ],\n returns: {\n title: 'returns',\n type: {\n name: 'string'\n },\n description: 'Test'\n }\n }\n ],\n slots: [\n {\n name: 'header',\n description: 'Use this slot header'\n },\n {\n name: 'footer',\n description: 'Modal footer',\n scoped: true,\n bindings: [\n {\n title: 'binding',\n type: {\n name: 'mixed'\n },\n name: 'item',\n description: 'an item passed to the footer'\n }\n ]\n }\n ]\n}\n```\n\n## Change log\n\nThe change log can be found on the [Changelog Page](./CHANGELOG.md).\n\n## Authors and license\n\n[Rafael Escala](https://github.com/rafaesc92)\n\n[Bart Ledoux](https://github.com/elevatebart)\n\nMIT License.\n" | ||
| } |
No alert changes
Improved metrics
- Total package byte prevSize
- increased by4.46%
359260
No dependency changes