DEV Community

Cover image for Quick & easy documentation generation for Vue.js components
Bernhard Wittmann
Bernhard Wittmann

Posted on • Edited on

Quick & easy documentation generation for Vue.js components

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.

GitHub logo 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

build status License PRs Welcome Commitizen friendly Code style Support me

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 
Enter fullscreen mode Exit fullscreen mode

and then run vuese to generate the documentation

vuese gen
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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.

GitHub logo 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)

Collapse
 
vicventum profile image
Víctor Álvarez

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, and watch sections of the component?

Collapse
 
mccabiles profile image
Miguel

We are now starting a new project using Vue and this looks like something we really need. Thank you for sharing!

Collapse
 
idoshamun profile image
Ido Shamun

Looks good! Thanks for building such a great tool, I have to check it out :)

Collapse
 
navidshad profile image
Navid

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.