Table of Contents
URL: https://www.progressiverobot.com/vuejs-propdoc-document-components/
Every developer wants to read good documentation. Every developer wants to write good documentation. Few developers actually do. Let's take a look at a really simple way to both generate documentation for your Vue.js components and render it as well with propdoc.
Installation
Install <^>propdoc<^> like any other Vue plugin: via Yarn or NPM.
# Yarn
$ yarn add propdoc
# NPM
$ npm install propdoc --save
Documenting Components
The biggest feature of <^>propdoc<^> is the ability to write your documentation as properties on components. These are only used if you use <^>propdoc<^> to render the documentation. Otherwise they have no effect. It's a genius idea that I'm surprised doesn't seem to have been done before.
[label MyButton.vue]
<template>
<div class="my-button" :class="{
flat: isFlat,
raised: isRaised,
primary: isPrimary
}">
<slot></slot>
</div>
</template>
<script>
export default {
name: "my-button",
introduction: "A basic example button.",
description: "A basic button with the ability to be flat, raised, or be a primary button. Nothing super special. (I stink at writing documentation.)",
token: `<my-button isFlat isPrimary>Button Text</my-button>`,
props: {
isFlat: {
type: Boolean,
default: false,
note: 'Whether or not to use the flat version of the button. (No gradient or outline.)'
},
isRaised: {
type: Boolean,
default: true,
note: 'Whether or not to use the raised version of the button. (Has a drop shadow.)'
},
isPrimary: {
type: Boolean,
default: false,
note: 'Whether or not to use the primary coloring.'
}
}
}
</script>
Along with the usual built-in keys like <^>name<^> and <^>required<^> on the component and props, <^>propdoc<^> adds a few more:
- note: Tells what a prop does.
- introduction: A quick introduction to a component.
- description: A detailed description of the component. Supports Markdown.
- token: A bit of code demonstrating how to use the component.
Rendering Documentation
It's nice and easy to render out the documentation for your component too. Just add the <^>propDoc<^> component and pass your documented component to it in the <^>component<^> prop.
[label DocumentationComponent.vue]
<template>
<div>
<!-- Render the documentation for MyButton -->
<prop-doc :component="MyButton"></prop-doc>
</div>
</template>
<script>
import propDoc from 'propdoc';
import MyButton from './MyButton.vue';
export default {
components: {
propDoc
},
data() {
return {
MyButton
}
}
}
</script>
