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

Quick & easy documentation generation for Vue.js components

berniwittmann profile image Bernhard Wittmann Updated on ・2 min read

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: vuese.org

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.

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 💪🏻

Posted on by:

berniwittmann profile

Bernhard Wittmann

@berniwittmann

Student - Developer - Productivity Tool Junkie - Privacy Enthusiast - Astronomy Geek

Discussion

markdown guide
 

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

 

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

 

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.