Generate a Markdown Documentation for a Vue file
# using in your project
npm install --save @vuedoc/md
# using in command line
npm install --global @vuedoc/md
- Generate documentation for component props
- Generate documentation for component data
- Generate documentation for computed properties with their dependencies
- Generate documentation for component events
- Generate documentation for component slots
- Generate documentation for component methods
- Support of JSDoc
First use comments to document your component (see test/fixtures/checkbox.vue for a complete example):
<template>
<div>
<label :for="id">
<!-- Use this slot to set the label -->
<slot name="label"></slot>
</label>
<textarea :id="id" v-on:keyup="keyup" v-on:input="input">
<!-- Use this slot to set the default value -->
<slot></slot>
</textarea>
</div>
</template>
<script>
/**
* The custom HTML `<textarea>` component.
*
* @author Sébastien
* @license MIT
*/
export default {
name: 'my-textarea',
props: {
/**
* Use this directive to create two-way data bindings with the component.
* It automatically picks the correct way to update the element based on the input type.
* @model
*/
value: { type: String },
/**
* Defines a unique identifier (ID) which must be unique in the whole document.
*/
id: { type: String, required: true },
/**
* This Boolean property indicates that the user cannot interact with the control.
*/
disable: { type: Boolean, default: false },
/**
* Define a custom theme for the component.
* @default new DefaultTextareaTheme()
* @type TextareaTheme
*/
theme: {
type: Object,
default: () => new DefaultTextareaTheme()
}
},
methods: {
/**
* Define if the control value is empty of not.
* @return {boolean} true if empty; otherwise false
*/
isEmpty () {
return !this.value || this.value.length === 0
},
/**
* @private
*/
input (e) {
this.value = e.target.value
/**
* Fired when the value is changed.
* @param {string} value - The updated value
*/
this.$emit('input', this.value)
},
/**
* @private
*/
keyup (e) {
/**
* Fired when a key is released.
*/
this.$emit('keyup')
}
}
}
</script>
Then use the CLI to generate the documentation:
# display the vuedoc.md version
vuedoc.md --version
# this print documentation in the standard output
vuedoc.md components/textarea.vue
# generate a Markdown documentation in a file docs/textarea.md
vuedoc.md components/textarea.vue --output docs/
# generate a Markdown documentation all components
vuedoc.md components/*.vue --output docs/
# update the API section of README.md with generated documentation
vuedoc.md components/textarea.vue --section "API" --output README.md
# combine generated documentations of all components into one
vuedoc.md --join components/*.vue --output README.md
# using pipe
cat components/textarea.vue | vuedoc.md
Output:
# my-textarea
The custom HTML `<textarea>` component.
- **author** - Sébastien
- **license** - MIT
## props
- `v-model` ***String*** (*optional*)
Use this directive to create two-way data bindings with the component. It automatically picks the correct way to update the element based on the input type.
- `id` ***String*** (*required*)
Defines a unique identifier (ID) which must be unique in the whole document.
- `disable` ***Boolean*** (*optional*) `default: false`
This Boolean property indicates that the user cannot interact with the control.
- `theme` ***Object*** (*optional*) `default: new DefaultTextareaTheme()`
Define a custom theme for the component.
## slots
- `label` Use this slot to set the label
- `default` Use this slot to set the default value
## events
- `input` Fired when the value is changed.
- `keyup` Fired when a key is released.
## methods
- `isEmpty()`
Define if the control value is empty of not.
--join # Combine generated documentation for multiple component files into only one
--level [integer] # Set the title level. An integer betwen 1 and 6
--output [file or dir] # The output directory. If absent, the STDOUT will be used
--section [section name] # Inject the generated documentation to a section. Works with `--output file`
--ignore-name # Ignore the component name on parsing
--ignore-description # Ignore the component description on parsing
--ignore-keywords # Ignore the component keywords on parsing
--ignore-slots # Ignore the component slots on parsing
--ignore-props # Ignore the component props on parsing
--ignore-computed # Ignore the component computed properties on parsing
--ignore-data # Ignore the component data on parsing
--ignore-methods # Ignore the component methods on parsing
--ignore-events # Ignore the component events on parsing
Options
name | type | description |
---|---|---|
level | integer | Set the title level. An integer betwen 1 and 6 |
output | string | The output of the documentation. Can be a directory or a Markdown file. If absent, the STDOUT will be used |
section | string | Inject the generated documentation to a section. Works with options.output as Markdown file output |
join | boolean | Combine generated documentation for multiple component files into only one |
For parsing options please read the @vuedoc/parser documentation
Usage
const vuedoc = require('@vuedoc/md')
const options = {
filename: 'test/fixtures/checkbox.vue'
}
vuedoc.md(options)
.then((document) => console.log(document))
.catch((err) => console.error(err))
@public
By default all commented members are public; this mean they will be part of the documented members.@protected
Commented members with this will be ignored.@private
Commented members with this will be ignored.
@default {description}
Commented prop will use the provided description as default prop description. This option may be helpfull in case the prop type is an object or function.@type {typeName}
Commented prop will use provided type name as type instead of type in source code. This option may be helpfull in case the prop type is an object or a function, which you may want to further detail with@typedef
in another place.
vuedoc.md
has been used to generate documentation of bellow components:
vx-input
: https://gitlab.com/vx-components/inputvx-checkbox
: https://gitlab.com/vx-components/checkboxvx-textarea
: https://gitlab.com/vx-components/textareaFormSchema Native
: https://gitlab.com/formschema/native
jsdoc-vuedoc
: https://github.com/ccqgithub/jsdoc-vuedoc
Under the MIT license. See LICENSE file for more details.