Did you ever lose oversight over the components of your Vue application?
If that's the case, you should definitely care about documenting your components. So what is the first idea here: Fire up a page in a wiki and just write down what each component does. However this may not be the best approach, because people tend to forget updating the documentation (or just don't want to, like myself).
So why don't automatically generate a slick documentation page directly from your code? But how?
Don't worry! vuese has your back. It can autogenerate documentation for your components and renders it as a neat & simple html page.
vuese / vuese
đ€ One-stop solution for vue component documentation. Original org: https://github.com/vuese
vuese
One-stop solution for vue component documentation
This project is supported by our Backers
Document
For detailed documentation: https://vuese.github.io/website/
Overview
Vuese Automatically generate documentation for your vue
component, and provides a variety of solutions for generating component documentation to meet your different needs.
@vuese/cli
@vuese/cli is a command line tool that is very simple to use. If you want to quickly build a documentation site for your vue
component or just want to generate markdown
document for your vue
component, then this tool might be a good choice. Please go to the details: @vuese/cli
@vuese/parser
The @vuese/parser module is the parser for the vue
component, @vuese/cli internally parsing the vue
component via the @vuese/parser module and extract the information we want. You can do any more advanced things with the interface provided by the @vuese/parser module. For the API
documentation, please go to @vuese/parser
Online experience
Visit the following đâŠ
You can add it to your Vue project right now, by installing it with:
npm install -g @vuese/cli
and then run vuese to generate the documentation
vuese gen
That's all, I swear đđ»
Now let's take a look at how it works
Imagine we have the following component:
<template>
<div>
<!-- Form header -->
<slot name="header">
<!-- `<th>title</th>` -->
<th>title</th>
</slot>
</div>
</template>
<script>
// This is a description of the component
export default {
name: 'TestComponent',
props: {
// The name of the form, up to 8 characters
name: {
type: [String, Number],
required: true,
validator () {}
}
},
methods: {
// @vuese
// Used to manually clear the form
clear () {
// Fire when the form is cleared
// @arg The argument is a boolean value representing xxx
this.$emit('onclear', true)
}
}
}
</script>
This results in this neat html page:
vuese retrieves the data and annotations from slots, props, methods and events and for the component itself directly from the code. As you can see it even extracts the type and required state from the name
prop.
You can check out the result here: https://berniwittmann.github.io/vuese-demo/index.html
I also created a small repo, where you can play around with the annotations and get a feeling of how simple it is.
BerniWittmann / vuese-demo
Short demo of Vuese Documentation Generation for Vue Components
Quick & easy documentation generation for Vue Components with vuese - Demo
This repo is a short demo of the tool vuese to create component documentation for Vue.js components.
The accompanying blog post can be found on dev.to
Result
Setup
Install the dependencies
npm install
Generate docs
Generate the docs by running
npm run docs
So have fun creating your component documentation and definitely check out vuese.org for more information.
Thanks for reading and I'd be glad about some feedback, since this is my first blog post ever đȘđ»
Top comments (4)
Hello! Thank you very much for the info, it was just what I needed to implement in my work. One question, additionally does it also work for the
data
,computed
, andwatch
sections of the component?We are now starting a new project using Vue and this looks like something we really need. Thank you for sharing!
Looks good! Thanks for building such a great tool, I have to check it out :)
This was cool, I used dartDoc module in dart language that use same concept for generating document and serve it. now I switched to Vue and currently need exactly this module.
thank you.