vue-block-documentation

A CLI generator to generate API documentation vue-block-system projects

Install

$ npm install -g vue-block-documentation

Commands

To use the generator open your console and change directory to the src directory of your vue-block-system project.

init-block-documentation

This will initialize the block documentation tool in your project, it will ask you to confirm some settings. This will most likely mean pressing enter until it's done.

$ init-block-documentation

generate-block-documentation

This is where the magic happens. Running this fill scan the block directory annd create a documentation folder in the src folder. Opening this on a webserver will display your generated documentation.

$ generate-block-documentation

Options:

• -i, --input <input>: Override the input directory.
• -o, --output <output>: Override the output directory.

Typing your block data

The tool will scan the block folders for the {BlockName}Data.js files, this file should contain all the data provided by your API. Describing the data is done by using Vue-Types.

Basic example

import VueTypes from 'vue-types';
 
export default {
    heading: VueTypes.string.isRequired,
    paragraph: VueTypes.string.isRequired,
    image: VueTypes.shape({
        src: VueTypes.string.isRequired,
        alt: VueTypes.string.isRequired,
    }).isRequired,
};

Using external objects

To avoid having to redefine the same object over and over again you can also import js files that describe the shape of the reusable object

ImageDataObject.js

import VueTypes from 'vue-types';
 
export default {
    src: VueTypes.string.isRequired,
    alt: VueTypes.string.isRequired,
};

BlockFooData.js

import VueTypes from 'vue-types';
import ImageDataObject from './image-data-object';
 
export default {
    heading: VueTypes.string.isRequired,
    paragraph: VueTypes.string.isRequired,
    image: VueTypes.shape(ImageDataObject).isRequired,
};

Adding custom descriptions and placeholders

When generating API documentation it also outputs example json structures, for easy development you want this to be as accurate as possible for the backender building your API. To create better documentation you can add descriptions and placeholder values into your object describing the object. You do this by adding a comment block above your data object. The structure for adding descriptions and placeholder is as followed:

@param {description|placehoder} [NAME_OF_YOUR_PARAM] Your description goes here...

This could end up in the following:

import VueTypes from 'vue-types';
 
/**
 * @param {description} heading This is the heading of the component
 * @param {placeholder} heading Lorem ipsum dolor sit amet
 *
 * @param {description} paragraph This is the paragraph of the component
 * @param {placeholder} paragraph Lorem ipsum dolor sit amet
 *
 * @param {description} image this is the image object of the component
 *
 * @param {description} image.src this is the source of your image
 * @param {placeholder} image.src path/to/image.jpg
 *
 * @param {description} image.alt this is the alt text for your image 
 * @param {placeholder} image.alt path/to/image.jpg 
 */
export default {
    heading: VueTypes.string.isRequired,
    paragraph: VueTypes.string.isRequired,
    image: VueTypes.shape({
        src: VueTypes.string.isRequired,
        alt: VueTypes.string.isRequired,
    }).isRequired,
};

Notes:

1. All imported files should be javascript files and will be parsed as es2015.
2. When using external object, descriptions and placeholders are shared amongst all parent files!

Demo

This tool wil only work on a vue-block-system project. I've created an example output so you can preview what the output might look like!

Check the example output online.