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
First use comments to document your component (see test/fixtures/checkbox.vue for a complete example):
<template>
<div>
<!-- Use this slot to set the label -->
<label :for="id"><slot name="label"></slot></label>
<textarea :id="id" @keyup="keyup" @input="input">
<!-- Use this slot to set the devault value -->
<slot></slot></textarea>
</div>
</template>
<script>
import _ from 'lodash'
/**
* 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 }
},
methods: {
/**
* Define if the control value is empty of not.
*/
isEmpty () {
return !this.value || this.value.length === 0
},
/**
* @private
*/
input (e) {
this.value = e.target.value
/**
* Fired when the value is changed.
*/
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
# comone 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.
## slots
- `label` Use this slot to set the label
- `default` Use this slot to set the devault 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.
vuedoc.md
has been used to generate documentation of bellow components:
vx-input
: https://github.com/vx-components/textareavx-checkbox
: https://github.com/vx-components/textareavx-textarea
: https://github.com/vx-components/textareavue-json-schema
: https://github.com/demsking/vue-json-schema
jsdoc-vuedoc
: https://github.com/ccqgithub/jsdoc-vuedoc
Under the MIT license. See LICENSE file for more details.